Configuration

The .verun.json file controls how Verun sets up your project for each task. Place it in your project root.

Fields

Setup Commands

The setup array runs sequentially when a new task is created. Use it to copy environment files, install dependencies, and start dev servers.

{
  "setup": [
    "cp .env.example .env",
    "pnpm install",
    "pnpm run dev"
  ],
  "ports": [3000, 5173],
  "env": {
    "NODE_ENV": "development"
  }
}

Each setup command runs inside the task's isolated worktree. If any command fails, the task status shows an error and the agent session does not start.

Examples

Node.js Application

{
  "setup": [
    "cp .env.example .env",
    "npm install",
    "npm run dev"
  ],
  "ports": [3000],
  "env": {
    "NODE_ENV": "development"
  }
}

Python Service

{
  "setup": [
    "python -m venv .venv",
    "source .venv/bin/activate && pip install -r requirements.txt",
    "source .venv/bin/activate && python manage.py runserver"
  ],
  "ports": [8000],
  "env": {
    "DJANGO_SETTINGS_MODULE": "config.settings.dev"
  }
}

Monorepo

{
  "setup": [
    "pnpm install",
    "pnpm --filter api run dev",
    "pnpm --filter web run dev"
  ],
  "ports": [3000, 4000, 5173],
  "env": {
    "NODE_ENV": "development",
    "MONOREPO": "true"
  }
}

Lifecycle Hook Behavior

1. A new task is created → a worktree is checked out.
2. Setup commands run sequentially in the worktree directory.
3. If env is set, environment variables are injected before commands run.
4. If ports is set, Verun maps each port to the task to avoid conflicts across parallel tasks.
5. Once all setup commands succeed, the task is marked ready and an agent session can start.

Default Agent

Set the agent field to pre-select an agent provider for new sessions:

{
  "agent": "claude-code",
  "setup": ["npm install"]
}

Valid values: claude-code, openai-codex, google-gemini, cursor.