Hooks

Hooks run shell commands at points in a sandbox’s lifecycle. They’re how you install dependencies, select a runtime, or do any one-time setup so the agent starts from a ready-to-work environment.

SandboxReady

SandboxReady is the hook that runs once the sandbox is up and your repository is checked out — before preview processes start. Provide an array of commands; they run in order.

{
  "hooks": {
    "SandboxReady": [
      { "command": "source /usr/local/share/nvm/nvm.sh && nvm use 24" },
      { "command": "bun install" }
    ]
  }
}

Each entry is an object with a command string. Commands run in your repository’s working directory.

Environment variables

Hook entries accept the same env and secretEnv blocks as preview processes:

• env — literal environment variables for that command.
• secretEnv — variables resolved from workspace secrets at runtime. Each entry maps the variable your command reads to a workspace secret key; the value never appears in your repository.

{
  "hooks": {
    "SandboxReady": [
      { "command": "bun install" },
      {
        "command": "bun run db:migrate && bun run db:seed",
        "env": { "NODE_ENV": "development" },
        "secretEnv": { "SEED_API_KEY": "SEED_API_KEY" }
      }
    ]
  }
}

Because hooks run through a shell, injected variables are also available directly in the command string as $VAR — no placeholder syntax needed.

When a run provisions resources, the resource’s variables (for example a database branch URL) are injected into that repo’s hooks automatically. If the same variable is defined in more than one place, a resolved secret wins over a resource variable, which wins over plain env — the same precedence previews use.

A secretEnv entry that references a missing workspace secret fails only that command — it is reported in the timeline with the missing key, and the remaining hooks still run.

What to put here

• Install dependencies — bun install, npm ci, pip install -r requirements.txt, etc.
• Select a runtime/toolchain — e.g. activate a Node version.
• One-time setup — generate code, prepare a database schema, seed fixtures.