Skip to main content
Setup is the editable project-level object used to prepare future agent runs in the Dev environment settings area. It defines:
  • VM size — compute resources for runs
  • Initialize — blocking setup for a fresh environment or snapshot build, after configured environment variables are injected
  • Update after checkout — blocking maintenance after a later checkout from reused or snapshotted state, with environment variables available
  • Startup — blocking service startup after setup is ready, with environment variables available
  • Commands — named executable commands agents may run while working; they never run automatically during Setup
  • Hooks — optional pre/post tool hooks
Read Setup with GET /setup and save it with PATCH /setup. The read response reports which source is authoritative: setup, legacy, or none. Saving applies the new Setup to future runs immediately; revision history and rollback are managed internally. Snapshots are separate: enabling or disabling cached VM state does not change Setup, and Setup can be saved or tested whether or not Snapshots are enabled. Within each lifecycle phase, scripts for independent repositories execute in parallel. A fresh environment runs Initialize and then Startup; it does not immediately repeat Update after checkout. Avoid putting the same expensive install in both phases unless it is required in both fresh and post-checkout states. 
{
  "source": "setup",
  "legacyHooks": {
    "status": "ignored",
    "repositories": ["acme/app"],
    "checkComplete": true
  },
  "setup": {
    "vmSize": "medium",
    "repositories": [
      {
        "repository": "acme/app",
        "branch": "main",
        "scripts": {
          "initialize": "pnpm install",
          "updateAfterCheckout": null,
          "startup": "pnpm dev"
        },
        "commands": [
          {
            "name": "Test",
            "command": "pnpm test"
          }
        ]
      }
    ],
    "hooks": { "pre": { "bash_run": ["pnpm lint"] } }
  }
}

​
Migrating deprecated hooks

If source is legacy, .capy/settings.json hooks remain active until you explicitly switch. Carry any needed scripts and tool hooks into Setup, then update with ?replaceLegacyHooks=true; afterward Setup is authoritative and legacy hooks are ignored. Legacy warm pool is separate deprecated infrastructure and does not use Setup. You can save Setup and test a snapshot while Legacy warm pool remains enabled; the test runs the full disposable capture, restore, and warm-up lifecycle without promoting the snapshot. After validation, disable the pool before enabling Snapshots.
Do not include secret values, credentials, or environment variable values in Setup. Configure environment variables separately in the UI; the public API omits them and rejects these fields.