> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Configure the project's dev environment

**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.

On a reused environment, Capy selects the lifecycle per repository. A changed
Setup revision or a repository that has not been prepared runs **Initialize**
then **Startup**. A changed branch or resolved commit runs **Update after
checkout** then **Startup**. An unchanged repository runs **Startup** only.

```json theme={null}
{
  "source": "setup",
  "legacyHooks": {
    "status": "ignored",
    "repositories": ["acme/app"],
    "checkComplete": true
  },
  "setup": {
    "vmSize": "medium",
    "repositories": [
      {
        "repository": "acme/app",
        "branch": "main",
        "scripts": {
          "initialize": "pnpm install",
          "updateAfterCheckout": "pnpm install --frozen-lockfile",
          "startup": "nohup pnpm dev >/tmp/dev.log 2>&1 &"
        },
        "timeouts": {
          "initialize": 900,
          "updateAfterCheckout": 300,
          "startup": 300
        },
        "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.

<Warning>
  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.
</Warning>