Runs

What Are Runs?

A run is a single agent execution. You provide a prompt and a repository — coSPEC provisions a sandbox, runs the agent, and returns the output. Each run is isolated, time-limited, and fully audited.

Creating a Run

Start a run by sending a prompt and repository to the API:

Terminal

curl -X POST https://api.cospec.io/v1/runs \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-org/your-repo",
    "prompt": "Refactor the auth middleware to use JWT",
    "template": "your-template",
    "model": "sonnet"
  }'

See the Create Run API reference for all available fields.

Run Lifecycle

pending → running → completed | failed | cancelled

Status	Description
`pending`	Run is queued, sandbox is being provisioned
`running`	Agent is executing inside the sandbox
`completed`	Agent finished successfully
`failed`	Agent hit a guardrail or encountered an error
`cancelled`	Run was cancelled via the API

Outputs

Outputs are detected automatically based on what the agent does during the run. You don't configure them upfront — they are collected as the agent works.

Type	Detected when
`text`	Agent produces a final text response
`branch`	Agent pushes changes with `git push`
`pr`	Agent creates a pull request with `gh pr create`
`issue`	Agent creates an issue with `gh issue create`

A single run can produce multiple outputs. For example, an agent might push a branch and open a pull request in the same run.

Guardrails

Guardrails cap resource usage per run. Set them on the run directly or as defaults on a template.

Guardrail	Range	Default	Description
`maxTurns`	1–1000	100	Maximum agent turns
`maxCostUsd`	$0.01–$1000	$5	Maximum Anthropic API cost
`timeoutSeconds`	30–3600	1800	Maximum wall-clock time

When a guardrail triggers, the run stops with status: failed and a failReason of max_turns, max_cost, or timeout.

Environment Variables

Pass per-run environment variables using the env field. These are merged with template defaults — run values win on conflict.

Managing Runs

Use the API to monitor, cancel, and list runs. See the Runs API reference for details.