--- title: "Set up your project" description: "Run one command in your project: AgentTwin finds a workflow, runs it on twins, breaks it, and proves the fix." canonical: "https://agenttwin.si/docs/quickstart/" --- # Set up your project Run one command in your project: AgentTwin finds a workflow, runs it on twins, breaks it, and proves the fix. Open a terminal in your project's main folder and run: ```sh npx agenttwin ``` That is the whole setup. No account, Docker, provider keys or config file is needed. AgentTwin finds a workflow in your code that calls outside services, runs it against twins of those services, breaks things the way production does, and shows what your code did to them. For optional practice first, use the [sample test](/docs/example/). ## 1. What happens when you run it The command works through seven steps and prints each one: | Step | What AgentTwin does | | --- | --- | | **Scan** | Reads your source and picks the workflow that does the most to outside services, such as an exported function, a route handler or a script you run with `node`. | | **Twin** | Starts a working twin of each service the workflow calls: Stripe, Slack, Postgres, AWS and others, plus your own internal APIs. | | **Run** | Runs the workflow once with nothing broken. This clean run has to pass before any fault counts. | | **Break** | Reruns it with one fault at a time. Examples: a payment succeeds but the reply is lost, a service answers 500, a reply arrives after your timeout, a webhook is delivered twice. | | **Find** | Compares what each service recorded with what should have happened. | | **Fix** | Proposes a change for the failures it has a known safe fix for. Nothing is changed yet. | | **Show** | Prints the impact, the proposed diff and where the evidence was saved. | **You should see** a list of runs marked PASS or FAIL, then the impact in plain terms. For example: ```text Impact Would have charged $12.00 twice Channel C_DEMO would have received 2 copies of the same message ``` AgentTwin chooses the workflow and makes up the starting data, inputs and expected results from your source. Review them in the scenario file the command prints. To test a different workflow, name it: ```sh npx agenttwin --workflow "node app.mjs" ``` The name is what the scan printed: an exported function name, a route such as `POST /checkout`, or `node ` for a script. ## 2. Apply the fix Your source isn't changed until you say so. Answer **y** when the command asks, or apply the fix without a prompt: ```sh npx agenttwin --workflow "node app.mjs" --fix --yes ``` AgentTwin applies the change, then reruns the exact failing scenario. It keeps the change only if that run now passes, the clean run still passes, and the fix holds across five different random seeds. Otherwise it puts your source back. **You should see:** ```text ✓ Held across 5 of 5 seeds (the failing one and four others) ✓ Locked as a regression script_app_mjs_timeout_after_write ``` Some failures have no automatic fix, for example a missing write after a 500 error. Those are listed as "Not fixed automatically", along with the evidence that shows where to look. Hand the result to your coding agent, change the code, and run the command again. ## 3. Keep it fixed Every proven fix is saved under `.agenttwin/regressions/`. Commit that folder. The command prints how to run those saved tests on every pull request, and [pull request checks](/docs/pull-request-checks/) explains the setup. ## 4. See results in your dashboard (optional) Results stay on your computer unless you connect an account. To send them to the dashboard: ```sh npx agenttwin login ``` Then run `npx agenttwin` again, or `npx agenttwin sync`. Results then show up under **Runs** at [agenttwin.si/dashboard](https://agenttwin.si/dashboard/). Sync sends run evidence and discovery information, not your source code (fix diffs are uploaded only if you set `AGENTTWIN_SYNC_FIX_DIFFS=1`). Set `AGENTTWIN_SYNC=0` to keep a connected terminal from syncing. ## What runs where - **Your code runs on this computer** as a normal Node.js process. AgentTwin routes its calls to twins running in the same process. Calls to any other host are blocked and listed, so a test can't charge a real card or send a real email. - **This isn't a sandbox.** It isn't a VM or a container. Run it only on code you would run yourself. For an isolated run, use `npx agenttwin test`, which runs in local Docker. - **Models aren't called.** Model replies come from a script, so no model provider is contacted and nothing is billed. - **Files are written to `.agenttwin/`** in your project: the scenario, run evidence, proofs and regressions. Your source changes only when you apply a fix.
What you need and what's supported - **Node.js, any version.** Node.js 20 or newer runs directly. On older versions, npx runs the CLI on Node.js 22, with nothing to install. - **A JavaScript or TypeScript project that runs on Node.js.** Supported workflows are exported functions, Express-style and Next.js route handlers, and scripts run with `node`. Discovery recognizes other languages, but the one-command flow runs only Node.js code today. - **Twins model the operations listed in `npx agenttwin contracts`.** A host with no dedicated twin gets a general stateful REST twin, and the output says so. Postgres is a wire-protocol twin that supports a small subset of SQL.
## If it doesn't find a workflow `No workflow found that AgentTwin can run` means no exported function, route handler or script reaches an outside service in a way the scan can follow. Try these: - Run `npx agenttwin init` to see everything discovery found, and why each candidate was or wasn't chosen. - Export the handler you want to test, or point at it with `--workflow`. - Run `npx agenttwin demo` to watch the full loop on a sample app. More fixes are in [troubleshooting](/docs/troubleshooting/). ## Other ways to start - **Guided dashboard path.** Run `npx agenttwin init` to connect the project. In the dashboard, choose **Prepare a test**. Your coding agent, Codex CLI or Claude Code, proposes the test, and you approve it with `npx agenttwin prepare review --id REQUEST_ID`. Then run it in Docker with `npx agenttwin test --preparation REQUEST_ID`. [Workflow preparation](/docs/preparation/) covers each step. - **Write the test yourself.** Describe the services, starting data and checks in a world file, then run `npx agenttwin run --file world.json`. See [worlds](/docs/worlds/). - **From your coding agent.** `npx agenttwin mcp` serves these tools to Claude Code, Codex, Cursor and other agents. See [MCP](/docs/mcp/).