# Macrofold documentation

> Persistent cloud agents: projects, files, Git, APIs, and a terminal CLI.

## Start here

- [Documentation](https://macrofold-staging.vercel.app/docs/raw/index.md): Build with persistent cloud agents from the dashboard, API, or terminal.
- [Quickstart](https://macrofold-staging.vercel.app/docs/raw/quickstart.md): Create a project, start an agent, and review its saved work.
- [Run locally](https://macrofold-staging.vercel.app/docs/raw/local-development.md): Start the free local simulator and test customer workflows.
- [Core concepts](https://macrofold-staging.vercel.app/docs/raw/concepts.md): Understand projects, workspaces, sessions, runs, and checkpoints.

## Guides

- [Dashboard](https://macrofold-staging.vercel.app/docs/raw/dashboard.md): Navigate projects, files, run history, access, and usage.
- [Runs and agents](https://macrofold-staging.vercel.app/docs/raw/runs.md): Select a harness, follow progress, continue work, and cancel safely.
- [Workspaces and Git](https://macrofold-staging.vercel.app/docs/raw/workspaces.md): Persist files, create branches, restore checkpoints, and synchronize GitHub.
- [Connections and access](https://macrofold-staging.vercel.app/docs/raw/connections.md): Bring provider keys and grant agents access to applications and MCP tools.
- [Web search](https://macrofold-staging.vercel.app/docs/raw/search.md): Configure a search provider and understand search behavior and billing.
- [Billing and limits](https://macrofold-staging.vercel.app/docs/raw/billing.md): Understand plans, concurrency, budgets, reserved credits, and retention.

## Build with the API

- [API quickstart](https://macrofold-staging.vercel.app/docs/raw/api/quickstart.md): Create a project and stream your first API-triggered run.
- [API conventions](https://macrofold-staging.vercel.app/docs/raw/api.md): Authenticate requests, paginate results, handle errors, and retry mutations.
- [Streaming and webhooks](https://macrofold-staging.vercel.app/docs/raw/api/events.md): Reconnect to run events and verify reliable webhook delivery.
- [Terminal CLI](https://macrofold-staging.vercel.app/docs/raw/cli.md): Link a project, chat remotely, use worktrees, and transfer files.
- [SDKs](https://macrofold-staging.vercel.app/docs/raw/sdk.md): Choose a Macrofold client for TypeScript, Python, Go, Rust, or Java.
- [TypeScript SDK](https://macrofold-staging.vercel.app/docs/raw/sdk/typescript.md): Use typed requests and recoverable event streams in TypeScript.
- [Python SDK](https://macrofold-staging.vercel.app/docs/raw/sdk/python.md): Integrate runs and durable streams with the Python client.
- [Go SDK](https://macrofold-staging.vercel.app/docs/raw/sdk/go.md): Make typed API requests and stream agent progress in Go.
- [Rust SDK](https://macrofold-staging.vercel.app/docs/raw/sdk/rust.md): Make typed API requests and stream agent progress in Rust.
- [Java SDK](https://macrofold-staging.vercel.app/docs/raw/sdk/java.md): Make typed API requests and stream agent progress in Java.

## Deploy and operate

- [Self-hosting](https://macrofold-staging.vercel.app/docs/raw/self-hosting.md): Understand the hosting components and choose a deployment guide.
- [Deploy on Vercel](https://macrofold-staging.vercel.app/docs/raw/self-hosting/vercel.md): Configure and deploy the application, database, storage, and native runtime.
- [Environment configuration](https://macrofold-staging.vercel.app/docs/raw/self-hosting/environment.md): Keep local, runtime, and migration configuration separate.
- [PostgreSQL and Neon](https://macrofold-staging.vercel.app/docs/raw/self-hosting/database.md): Configure restricted roles, connection pooling, migrations, and recovery.
- [Provider integrations](https://macrofold-staging.vercel.app/docs/raw/self-hosting/integrations.md): Register models, tools, billing, storage, email, and GitHub.
- [Usage and operator reporting](https://macrofold-staging.vercel.app/docs/raw/operations.md): Read activity, execution demand, account metrics, and management MCP reports.

## Resources

- [Troubleshooting](https://macrofold-staging.vercel.app/docs/raw/troubleshooting.md): Recover from setup failures, access errors, interrupted streams, and conflicting edits.
- [Read with an agent](https://macrofold-staging.vercel.app/docs/raw/agents.md): Discover Markdown guides, schemas, and navigation indexes for coding agents.

## Reference

- [OpenAPI](https://macrofold-staging.vercel.app/openapi.json)
- [Interactive API reference](https://macrofold-staging.vercel.app/reference)
- [Complete documentation](https://macrofold-staging.vercel.app/llms-full.txt)