API Reference
Verun local API reference — manage projects, tasks, and agent sessions programmatically via localhost REST endpoints. No authentication required.
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
projects (1) → tasks (many) → sessions (many) → output_lines (many)Endpoints
GET /api/projects
List all added projects.
[
{
"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.
{
"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.
[
{
"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.
{
"id": "uuid",
"task_id": "uuid",
"agent": "claude-code",
"status": "starting",
"pid": 12345
}DELETE /api/sessions/:id
Kill a running session.
{
"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") |