# Documentation

Run Codex, Claude Code, OpenCode, Hermes, DeepSeek Harness, or Pi through an API, CLI, or dashboard. Give agents persistent files they can return to across tasks.

## Start building

- **[Build with AI](https://staging.macrofold.ai/docs/raw/agents.md):** copy a setup prompt into your coding agent and describe your feature.
- **[API quickstart](https://staging.macrofold.ai/docs/raw/api/quickstart.md):** create a project, submit a task, and print its result.
- **[Dashboard quickstart](https://staging.macrofold.ai/docs/raw/quickstart.md):** run and review a task without writing code.

## Choose where Macrofold runs

| Option | You manage | Start here |
| --- | --- | --- |
| Macrofold Cloud | Your application, projects, permissions, and usage | [Connect to Cloud](https://staging.macrofold.ai/docs/raw/cloud.md) |
| Self-hosted | Your Macrofold deployment and its infrastructure | [Self-hosting guide](https://staging.macrofold.ai/docs/raw/self-hosting.md) |

The same API, SDK, CLI, and feature guides apply to both. Use the origin and credentials for your deployment; enabled integrations, model availability, and limits depend on its configuration. For a free first experiment, use [local simulation](https://staging.macrofold.ai/docs/raw/local-development/simulation.md).

## Learn the essentials

A **project** groups work. A **workspace** holds its files. A **run** performs a task. [Core concepts](https://staging.macrofold.ai/docs/raw/concepts.md) explains what persists.

- [Runs and agents](https://staging.macrofold.ai/docs/raw/runs.md): select a harness, stream output, continue, and cancel.
- [Workspaces and Git](https://staging.macrofold.ai/docs/raw/workspaces.md): edit files, restore checkpoints, and synchronize a repository.
- [Share files between agents](https://staging.macrofold.ai/docs/raw/workspaces/shared-agents.md): take turns in one workspace or use separate branches in parallel.
- [Connections](https://staging.macrofold.ai/docs/raw/connections.md): model keys, named app accounts, and MCP tools.
- [Triggers and schedules](https://staging.macrofold.ai/docs/raw/triggers.md): start work from Slack, webhooks, or recurring prompts.
- [Dashboard](https://staging.macrofold.ai/docs/raw/dashboard.md) and [billing](https://staging.macrofold.ai/docs/raw/billing.md): review work, manage access, and control usage.

## Build a customer-facing agent

Read the [customer identity guide](https://staging.macrofold.ai/docs/raw/customer-agents.md), then run the [personal-agent application](https://staging.macrofold.ai/docs/raw/customer-agents/example.md). It keeps customer ownership, named agents, files, conversations and schedules connected. Add the optional [file memory starter](https://staging.macrofold.ai/docs/raw/customer-agents/memory.md) or use [customer-data recipes](https://staging.macrofold.ai/docs/raw/customer-agents/integrations.md) for an existing database or MCP service. Each guide includes setup, examples, recovery, validation and an explicit AI reading map.

## Go deeper

[API overview](https://staging.macrofold.ai/docs/raw/api.md) · [SDKs in five languages](https://staging.macrofold.ai/docs/raw/sdk.md) · [CLI](https://staging.macrofold.ai/docs/raw/cli.md) · [Streaming](https://staging.macrofold.ai/docs/raw/api/events.md) · [Errors and retries](https://staging.macrofold.ai/docs/raw/api/conventions.md) · [OpenAPI](https://staging.macrofold.ai/openapi.json) · [Troubleshooting](https://staging.macrofold.ai/docs/raw/troubleshooting.md)

## Develop and operate

[Local simulation, Docker, and cloud staging](https://staging.macrofold.ai/docs/raw/local-development.md) are development modes. [Self-hosting](https://staging.macrofold.ai/docs/raw/self-hosting.md) covers operating a deployment. [Architecture](https://github.com/Macrofold/Macrofold/blob/main/docs/architecture/README.md), the [codebase map](https://github.com/Macrofold/Macrofold/blob/main/docs/architecture/codebase.md), and [contributing](https://github.com/Macrofold/Macrofold/blob/main/CONTRIBUTING.md) explain how to change Macrofold itself.

Anyone can [contribute a harness through the Unified Harness Interface](https://staging.macrofold.ai/docs/raw/unified-harness-interface.md), reusing the existing execution, streaming, and persistence system.