Configuration

Configure Verun for your project using .verun.json — setup hooks, start command, ports, and environment variables for any project type.

The .verun.json file controls how Verun sets up each task for your project. Place it in your project root and Verun will pick it up automatically when you add the project.

Schema

{
  "hooks": {
    "setup": "cp \"$VERUN_REPO_PATH/.env\" .env && pnpm install",
    "destroy": "rm -rf node_modules"
  },
  "startCommand": "pnpm dev",
  "autoStart": true,
  "baseBranch": "main",
  "defaultAgentType": "claude"
}

Field	Type	Description
`hooks.setup`	`string`	Shell command run when a new worktree is created
`hooks.destroy`	`string`	Shell command run when a task is archived or deleted
`startCommand`	`string`	Dev server command run after setup
`autoStart`	`boolean`	Run the start command automatically for new tasks
`baseBranch`	`string`	Default branch new tasks fork from
`defaultAgentType`	`string`	Default agent for new sessions

Environment Variables

Every hook and start command receives these environment variables:

Variable	Description
`$VERUN_REPO_PATH`	Absolute path to your project root (not the worktree)
`$VERUN_PORT_0`	First port allocated to this task
`$VERUN_PORT_1` … `$VERUN_PORT_9`	Nine additional ports allocated to this task

Ports are auto-allocated per task starting at 10000. Task 0 gets 10000–10009, task 1 gets 10010–10019, and so on. No port configuration is needed — just use $VERUN_PORT_0 in your start command.

Examples

Node.js

{
  "hooks": {
    "setup": "cp \"$VERUN_REPO_PATH/.env\" .env && pnpm install"
  },
  "startCommand": "PORT=$VERUN_PORT_0 pnpm dev",
  "autoStart": true
}

Python

{
  "hooks": {
    "setup": "cp \"$VERUN_REPO_PATH/.env\" .env && python -m venv .venv && .venv/bin/pip install -r requirements.txt",
    "destroy": "rm -rf .venv"
  },
  "startCommand": "PORT=$VERUN_PORT_0 .venv/bin/python manage.py runserver 0.0.0.0:$VERUN_PORT_0",
  "autoStart": true
}

Monorepo (multiple services)

{
  "hooks": {
    "setup": "cp \"$VERUN_REPO_PATH/.env\" .env && pnpm install --frozen-lockfile"
  },
  "startCommand": "API_PORT=$VERUN_PORT_0 WEB_PORT=$VERUN_PORT_1 pnpm dev",
  "autoStart": true
}

Verun's own config

{
  "hooks": {
    "setup": "pnpm install --frozen-lockfile",
    "destroy": "rm -rf node_modules src-tauri/target"
  },
  "startCommand": "VITE_PORT=$VERUN_PORT_0 VITE_HMR_PORT=$VERUN_PORT_1 pnpm tauri dev"
}

Default Agent

Set defaultAgentType to pre-select an agent for new sessions in this project:

{
  "defaultAgentType": "claude"
}

Valid values: claude, codex, cursor, gemini, opencode.

Importing and Exporting

In Settings → Project, use Import from .verun.json to load config from the file into the UI, or Export to .verun.json to write the current UI settings back to the file. This keeps the file in sync so teammates who clone the repo get the same setup automatically.

Configuration

On this page