# Run and test the application

Choose where execution happens and whether you need real model reasoning. **New contributor? Start with [local simulation](https://staging.macrofold.ai/docs/raw/local-development/simulation.md).** It needs no provider account and makes no paid agent calls.

## Choose a development mode

| Mode                                                       | Where the application and agent run                                                           | Accounts and costs                                                                 | Availability                                                       |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Local simulation](https://staging.macrofold.ai/docs/raw/local-development/simulation.md)        | Dashboard, API, database, and worker on your computer; scripted agent activity                | No cloud or model account; free agent runs                                         | Working default                                                    |
| [Real agents in local Docker](https://staging.macrofold.ai/docs/raw/local-development/docker.md) | Local application and Docker sandbox; any of the six supported native harnesses                    | No Vercel account; a model provider key and inference budget                       | Complete API-to-Docker journey tested with scripted models           |
| [Real agents in cloud staging](https://staging.macrofold.ai/docs/raw/local-development/cloud.md) | Deployed application, database, storage, and Vercel Sandbox; clients can run on your computer | Access to a staging environment; cloud infrastructure and inference can cost money | Cloud adapter implemented; requires deployment and live acceptance |

A **harness** is the agent software, such as Codex or Claude Code. A **model** supplies its reasoning. A **sandbox** is the isolated machine where its commands and file edits happen. A local sandbox can still call a remote, paid model.

## Start

Follow the [two-terminal simulator setup](https://staging.macrofold.ai/docs/raw/local-development/simulation.md#start). It starts the actual dashboard and API at **http://localhost:3210**, with local PostgreSQL, captured email, and a separate worker.

The default setup does not launch Vercel sandboxes. Installing Docker or adding a model key does not switch simulated runs to real agents.

For real reasoning, choose the explicit [Docker profile](https://staging.macrofold.ai/docs/raw/local-development/docker.md) or [cloud staging](https://staging.macrofold.ai/docs/raw/local-development/cloud.md). Both require a reviewed model route and inference budget; staging also requires cloud resources.

## Try the API

Use the same [API quickstart](https://staging.macrofold.ai/docs/raw/api/quickstart.md) in each implemented mode: create an API key and project, submit a run and wait for its complete result. Point the client at the local or staging origin. Select `fixture-model` only for simulation; real execution needs an enabled model compatible with the selected harness.

Start with the SDK quickstart, [cURL guide](https://staging.macrofold.ai/docs/raw/api/http-quickstart.md), or the interactive API reference. Postman is optional; import [OpenAPI](https://staging.macrofold.ai/openapi.json) and set your service origin and Bearer token. The CLI and SDKs use that same API.

## Test

Choose tests based on the boundary you changed:

| Question                                               | Use                                                                                          | What a pass establishes                                                                      |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Does the application workflow work?                    | [Local domain and customer-journey tests](https://staging.macrofold.ai/docs/raw/local-development/simulation.md#test-your-changes) | API, database, dashboard, and client behavior with simulated execution                       |
| Can each real harness run tools and restore its files? | [Native Docker fixtures](https://staging.macrofold.ai/docs/raw/local-development/docker.md#run-the-existing-native-tests)          | Actual harness software works with deterministic model responses                             |
| Does our gateway speak to the actual provider?         | [Opt-in live provider tests](https://github.com/Macrofold/Macrofold/blob/main/docs/engineering/testing/live-integrations.md)                    | Selected real provider protocols and accounting, without launching an agent sandbox          |
| Does API-to-Docker work with free model fixtures?      | [Complete Docker journey](https://staging.macrofold.ai/docs/raw/local-development/docker.md#test-the-complete-journey-for-free)    | Actual API, SQL worker, native tools, gateway, checkpoint and continuation                   |
| Does the entire real-agent journey work?               | [Cloud staging acceptance](https://staging.macrofold.ai/docs/raw/local-development/cloud.md#test-a-real-agent-journey)             | API admission through real sandbox execution, model calls, persisted files, and continuation |

Development modes and test levels are different. Mocked model responses let real harnesses execute tools, but cannot prove live reasoning or provider compatibility. A successful provider request alone cannot prove sandbox startup. The complete journey needs both together.

## Stop

Use the selected guide's shutdown steps: [simulation](https://staging.macrofold.ai/docs/raw/local-development/simulation.md#stop-and-resume), [Docker fixtures](https://staging.macrofold.ai/docs/raw/local-development/docker.md#cleanup), or [cloud staging](https://staging.macrofold.ai/docs/raw/local-development/cloud.md#stop-new-work).

## Further details

[Testing and CI](https://github.com/Macrofold/Macrofold/blob/main/docs/engineering/testing.md) owns the full suite catalog. [Implementation status](https://github.com/Macrofold/Macrofold/blob/main/docs/status/README.md) records measured acceptance; [development-mode architecture](https://github.com/Macrofold/Macrofold/blob/main/docs/engineering/development-modes.md) explains the shared execution integration and complete-journey acceptance boundary.