Dev environment

The dev environment is your project’s machine recipe: which setup scripts prepare a fresh machine, which commands the agent can run, which tool hooks apply, and how big the VM is. It’s the highest-leverage configuration you’ll do in Capy, because an agent that can’t run your tests can’t verify its work. On a machine where pnpm test works, the agent proves its changes; on a machine where nothing runs, it guesses and you find out in CI. Spend the twenty minutes. Every thread, task, and rebuilt machine in the project benefits from it, and a snapshot makes the result nearly free to boot.

Two ways to configure it

Open your project and go to Dev environment to edit machine size, per-repository setup scripts, and snapshots directly. Or ask Capy in any thread (“set up this project’s dev environment”) and it reads your manifests, writes the setup, and can verify it by running the scripts on its own machine. Agent edits and your edits land in the same configuration; every save creates a new version in one shared history. Setup is stored per repository. The shape, if you want to picture it:

{
  "vm_size": "large",
  "repositories": [
    {
      "repository": "acme/app",
      "scripts": {
        "initialize": "pnpm install --frozen-lockfile",
        "update_after_checkout": "pnpm install --frozen-lockfile",
        "startup": "nohup pnpm dev >/tmp/dev.log 2>&1 &"
      },
      "timeouts": { "initialize": 900 },
      "commands": [{ "name": "test", "command": "pnpm test" }]
    }
  ]
}

Scripts are optional; leave a phase empty when it has no work to do.

The three setup phases

Phase	When it runs	Default timeout
`initialize`	Once, on a fresh clone (new machines and snapshot builds)	900 s
`update_after_checkout`	When a reused or snapshot-restored checkout moves to a new commit	300 s
`startup`	After preparation on every fresh start and wake	300 s

Every timeout is configurable from 60 to 3600 seconds. The selection is per repository: a fresh clone runs initialize then startup; a restored or reused checkout fetches and fast-forwards its branch, runs update_after_checkout only when HEAD actually moved, then runs startup. A failed initialize is retried on the existing checkout until a run succeeds.

initialize

Everything needed to make a clean clone usable: install dependencies, system packages, global tools, generated artifacts. It also runs during snapshot builds, so whatever it produces gets baked into the snapshot. If dependency installation needs a private registry, authenticate explicitly at the top of the script; a package-manager preinstall hook can’t authenticate the fetch that happens before it exists.

update_after_checkout

The repair phase: bring a prepared machine up to date after the checkout moves. Keep it fast and safe to rerun: sync dependencies from the lockfile, regenerate derived code. Don’t duplicate an expensive bootstrap here unless reused machines genuinely need it.

startup

Start the services the agent needs while working: dev servers, local databases. The script itself must exit, so background long-running processes and wait for readiness:

nohup pnpm dev >/tmp/dev.log 2>&1 &
for attempt in {1..30}; do
  curl -fsS http://127.0.0.1:3000 >/dev/null && exit 0
  sleep 1
done
exit 1

Make it idempotent. startup runs again when a machine wakes from sleep. Processes don’t survive sleep, so this script is what brings your services back, and a script that blindly starts a second server will trip over the first one’s port on reruns.

How scripts execute

Each script runs from its repository’s directory, in bash, under its timeout, as a user with passwordless sudo, with your environment variables loaded. A non-zero exit or a timeout fails the phase. A failed phase doesn’t kill the thread: the machine comes up, the thread gets a workspace warning naming the repository and phase, and the agent continues in a degraded workspace it will usually try to repair by hand. That self-repair costs you time and tokens on every machine; fix the script instead.

Commands

Commands are named, opt-in actions the agent can run while working: test, typecheck, build. They never run automatically; the agent reads them from setup and invokes them when relevant. Keep them executable and specific. Prose guidance like “always lint before committing” belongs in agent instructions, not here.

Tool hooks

Setup can store commands that run before or after specific agent tools:

{
  "post": {
    "edit": { "commands": ["pnpm prettier --write ${file_path}"] },
    "write": { "commands": ["pnpm prettier --write ${file_path}"] }
  }
}

Key hooks by real tool names (bash, edit, write, read, apply_patch), and optionally restrict one to an agent type (capy or review). A hook keyed to a name that isn’t a real tool never fires. Hook configuration ships today and the agent can read and write it; enforcement around tool calls is still rolling out, so don’t treat a hook as a security boundary yet.

What the agent can do itself

Capy reads and replaces the whole setup through its environment tools, which is what makes “ask Capy to update your dev environment” work. Two boundaries hold regardless: the agent sees environment variable names and whether each has a value, never the values, and no tool can set a variable’s value. Values are yours to manage in the app; see Environment variables and secrets.

PR reviews run on their own machine with a fresh checkout pinned to the exact PR head, credentials read-only and pushes disabled. Shared project variables apply there; personal and thread variables never do.

Getting started

Working with Capy

Machines & configuration

Integrations

Admin

Resources

Dev environment

Two ways to configure it

The three setup phases

initialize

update_after_checkout

startup

How scripts execute

Commands

Tool hooks

What the agent can do itself

​Two ways to configure it

​The three setup phases

​initialize

​update_after_checkout

​startup

​How scripts execute

​Commands

​Tool hooks

​What the agent can do itself

Two ways to configure it

The three setup phases

initialize

update_after_checkout

startup

How scripts execute

Commands

Tool hooks

What the agent can do itself