API Reference

Verun exposes a local API for programmatic control. All endpoints run on localhost and require no authentication — the API is only accessible from your machine.

Data Model

text

projects (1) → tasks (many) → sessions (many) → output_lines (many)

GET/api/projects

List all added projects

json

[
  {
    "id": "uuid",
    "name": "my-app",
    "path": "/Users/dev/my-app",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/tasks

Create a new task for a project

json

{
  "id": "uuid",
  "name": "Refactor auth module",
  "branch": "sleepy-capybara-472",
  "worktree_path": ".verun/worktrees/sleepy-capybara-472/",
  "status": "ready",
  "project_id": "uuid"
}

GET/api/tasks/:id/sessions

List all sessions for a task

json

[
  {
    "id": "uuid",
    "task_id": "uuid",
    "agent": "claude-code",
    "status": "running",
    "created_at": "2025-01-15T10:35:00Z"
  }
]

POST/api/tasks/:id/sessions

Start a new agent session on a task

json

{
  "id": "uuid",
  "task_id": "uuid",
  "agent": "claude-code",
  "status": "starting",
  "pid": 12345
}

DELETE/api/sessions/:id

Kill a running session

json

{
  "status": "killed"
}

Configuration File

The .verun.json file supports these options:

Field	Type	Description
setup	string[]	Commands to run when a task is created
ports	number[]	Ports to auto-assign per task
env	Record<string, string>	Environment variables for tasks
agent	string	Default agent (e.g., "claude-code")