Local API and command-line client

Use the owner token with the local API or the bundled command-line client. Keep credentials out of repository files and shell history, and inspect an operation’s request and response contract before scripting mutations.

Use the authenticated client

Use npm run client -- --help for the HTTP client. It requires the explicit CODEFLOW_TOKEN printed/configured by the server and accepts CODEFLOW_URL for another configured origin. It never reads agent login files. JSON files and shell arguments are treated as data, not executed. Output files are created privately and never overwritten.

/api/v1/* exposes the same authenticated operations as /api/*. GET /api/v1/capabilities lists the new stable operation families. Existing unversioned clients remain compatible. Authentication, Host, Origin and phone session checks apply identically to both prefixes.

Paths below are relative to /api (or /api/v1). Requests with bodies use JSON. Successful mutations use the status shown where relevant; validation errors use 400, missing resources 404, and explicit concurrency conflicts 409. Errors contain an error string. No client-side mutation retry is automatic.

Readiness accepts roles as an object of provider IDs (strings or arrays). Concrete assignments must be installed, compatible and not signed out; unused providers are skipped. providers alone is an explicit required-provider list. With roles, it limits the eligible pool for auto assignments; without that limit, Auto considers registered providers. An Auto-team's roles.pool contains alternatives and needs at least one usable member (also within providers, if supplied), while its coordinator is required. An explicit empty scope fails readiness. Unknown authentication remains a warning. Omitting both roles and providers preserves the original checks of all installed providers.

Scope IDs must be 1–128 letters, digits, underscores, colons, slashes, periods or hyphens, beginning with a letter or digit. Provider values must be registered IDs or "auto"; lists allow at most 128 entries and roles allows at most 64 keys. Malformed scope returns HTTP 400. The composer sends its current workflow and assignments and discards displayed or in-flight reports when that selection changes.

Prompt improvement accepts up to 20,000 input/output characters and a 1,000-character summary. Context is limited to 50 names of 300 characters; optional source metadata contains kind=issue|pr|alert, integer number and a title of at most 200 characters. Quick mode supplies only the text and metadata; repository mode exports a pinned committed-HEAD snapshot with a fresh Git namespace. Source Git configuration, hooks, remotes, history, ignored/untracked content and executable provider configuration are not copied. Both use safe provider permissions and an in-process repository mutation lease; cleanup removes only the private directory after failure or cancellation, never resetting the source checkout or its index. See snapshot bounds. Snapshot preparation has a 60-second deadline. Inherited Git routing/configuration overrides are refused so the provider cannot accidentally target another checkout through its environment. Improve also requires absolute, nonempty PATH entries and currently supports macOS/Linux; Windows is refused until executable discovery is pinned and tested. Explicit SSH/container profiles return 400, shared accounts return 403, repository/policy conflicts return 409, the three-turn global concurrency limit returns 429, and provider/snapshot failures return 502. Closing the request cancels the turn; clients must not automatically retry it.

Verification profiles contain name, up to 12 checks, optional setup, and up to 48 requirements. Each check has a unique id, kind, command, optional title, required (default true), and timeoutMs (default five minutes, maximum 30 minutes). Kinds are build, typecheck, lint, unit, integration, browser, mutation, visual, accessibility, and custom. A requirement is {id, description, checks: [checkId, ...]}; an empty mapping remains uncovered. A failed mapped gate or uncovered criterion prevents verified status. Repeats are limited to 1–3; a mixed passing/failing result remains flaky. Baseline failures are evidence, not permission to ignore a required gate.

Standalone verification pins the requested commit, excludes uncommitted changes, and runs setup and gates on temporary worktrees. A setup or gate that changes tracked files, the staged tree, or HEAD is rejected with 409 before subsequent gates execute. Ignored and untracked generated output is permitted. Setup failure returns 422. Run-attached profile verification similarly produces a blocked report on candidate drift. Requirement coverage records the checks selected by the user; it does not prove those checks semantically exercise the criterion. Human file coverage is a separate, user-authored commit-bound record. See selective task reruns for budget, replay, retained-evidence and unchanged-result semantics. Client-authored teamRerun seeds are never accepted by run creation.

Paginated history and event feeds

GET /runs keeps the legacy full-list response when no limit query is supplied. With limit=1..100, it returns {runs, total, nextCursor?, nextBefore?}. Pass the opaque nextCursor as cursor on the next request; cursors preserve ties for runs created in the same millisecond. Optional q filters all indexed run metadata and project selects a project (including legacy repository-based membership). status=all|attention|running|passed|failing|flagged, pattern, agent, and repo filter the complete authorized index before totals and pagination. Passed requires completed execution and passing verification; blocked or unverified results are excluded. section=waiting|running|results selects a non-archived project-page section. The legacy before timestamp is supported but can omit timestamp ties; prefer cursor. Keep filters consistent between pages. Invalid cursors, status/section values and page sizes return 400.

GET /projects/:id/summary returns {live, archived, pending, week, sections}. week contains {runs, passed, costUsd} for the last seven days, including archived history. sections contains cursor pages for waiting, running and results, with complete totals. Fetch additional section pages through /runs. These totals never depend on which sidebar pages a browser has loaded.

The shared /stream connection accepts the approvals topic. It sends a {type: "snapshot", records: [...]} frame initially and whenever pending tool approvals change. Reconnects receive a fresh snapshot; approval decisions still use the single-action POST endpoint. Older hosts without this topic use the client's visibility-aware polling fallback.

GET /events?limit=1..100 is the bounded SSE run feed. Its initial hello contains the recent page, every running run and at most 100 older attention items, total, nextCursor, attentionTotal, attentionTruncated, and an optional attentionNextCursor. Older attention remains accessible through history; the rail displays the truncation. Without limit, the legacy full initial list remains available. Policy changes invalidate the feed generation. Reconnect using Last-Event-ID; a valid retained cursor resumes snapshots, while a stale cursor triggers a fresh hello. GET /runs/:id/events streams that run's retained events with a run-bound replay cursor. These are live feeds, not durable client acknowledgment queues.

Read-only external sources

Run creation accepts externalSourceId from the import response, or externalSourceRef: {integration, kind, key} for a server-side import. It rejects client-authored externalSource snapshots, invalid/expired IDs, and simultaneous ID/ref inputs. Snapshots expire after 30 minutes and the server retains at most 200. Imported context forces Safe permissions, removes secret-file copying, and requires network-disabled checks in a container or explicit host authorization. Forks and continuations inherit the trust boundary. Source text is task context; PR imports do not fetch or check out remote code. See external source setup and provider limits.

Outbound notifications

Destinations are configured only through server environment JSON/file with environment-variable references for HTTPS URLs and credentials. New destinations are disabled. Delivery uses no redirects, a ten-second timeout and at most three automatic attempts per batch. Changing the URL requires renewed opt-in. Unknown outcomes after restart require manual retry; recipients should deduplicate the persistent Idempotency-Key. Notification storage/configuration failure returns 503 and leaves delivery off. See configuration, disclosure, and delivery limitations.

Project memory analysis and revision commands

Create accepts repo, title, body, optional paths, tags, and applicability. Update accepts editable fields and optional accept: true; an ordinary edit never accepts a proposal automatically. Feedback accepts rating, optional note and runId; a run reference must have selected that exact entry revision. Analysis is heuristic and bounded: lexical similarity does not infer contradictions on its own. Deterministic semantic claims compare supported policies and structured boolean/text/numeric intervals only across overlapping applicability; unsupported prose is counted. Git freshness checks do not establish semantic correctness. See supported claims. Publication excludes imported/private/untrusted material and prior onboarding summaries. Memory APIs remain owner-only; shared project roles use the separate closed review surface described below.

Multi-service launch profiles

Profiles configure at most six services and bounded commands, relative working directories, dependencies, environment values and optional local HTTP health checks. The server assigns ports and peer URL variables. This starts local processes; it is not remote deployment or hosting. See launch profile configuration and lifecycle.

Automation inspection and replay

Daily schedules use {at: "HH:MM", timezone?: "IANA/Zone", days?: [0..6]}; Sunday is zero and an explicit empty weekday list is invalid. Omitted timezone uses server local time. Interval schedules use {every: minutes}. During a repeated local clock time, a daily schedule fires once on its first occurrence; a missing local time shifts forward by the clock gap. Webhook event history keeps at most 100 records and the pending queue at most ten. Replay preserves the saved event content, while rechecking current configuration and limits. It never merges results automatically.

Run creation accepts loop.verification, loop.maxTokens, loop.maxCostUsd, loop.agentContainer, and explicit approvals.tools. Token/cost limits count only provider-reported usage and are checked between operations. API-equivalent cost is not a subscription charge. Automated and locked-down runs never wait for native tool permissions. See agent containers, external sources, and maintenance.

The client has no automatic retry for mutations. A dropped response is not proof that an operation did not execute; inspect the run before repeating a creation.

Shared identities and project review

GET /auth/self, POST /auth/login {username,password} and POST /auth/logout bootstrap the local viewer/reviewer dashboard. Login sets a distinct session cookie; tokens and password/session hashes are never returned. Shared sessions require actual TLS or a direct loopback connection without forwarding headers. Owner account administration uses GET/POST /accounts, PUT /accounts/:id, and POST /accounts/:id/revoke-sessions, with the current account-state revision.

Shared routing is a closed allowlist. Project/run lists, result detail, safe events, diffs, coverage and exports are scoped before counts and cursors. Reviewers may record file coverage and POST /runs/:id/collaboration {branch,expectedHead,text}; both recheck current project membership and owned result HEAD. GET returns the separate human discussion. These comments never resume an agent. All execution, administrative and private-context operations remain owner-only. See roles, projections and session limits.

Team collaboration

A team board served by one code-flow instance (the team server) and the linked runners on teammates' computers share the routes below. Browser sessions (the owner and shared accounts) and per-machine runner credentials (Authorization: Bearer tr-…) use the same paths; the table says who may call. A runner credential reaches only /team/* and the enrolment route; every other API route answers 403 "This credential only reaches the team API", and the pages treat it as an anonymous visitor. The owner token is matched before a bearer is read as a runner credential. Runner mutations send content-type: application/json (the bundle upload application/octet-stream) and need no Origin header; browser mutations keep the same-origin JSON requirement of shared accounts. Board tasks are visible only in projects where the caller holds a role; people appear as an account id and display name, never with paths, transcripts, tokens or hashes. /v1/team/* and /v1/team-link/* aliases work, and GET /v1/capabilities lists the family as team-collaboration.

Mutations return the updated task and carry the task revision; a stale one fails with 409 "Task changed; reload before saving". A missing role answers 403 naming the role, an unknown or invisible id 404 "Task not found", an unknown team route 404 "Unknown team operation" (never falling through to owner routes) and unavailable team storage 503. Task saves and repository keys accept 64 KiB bodies, progress reports 192 KiB, checkpoint manifests 1.25 MiB, bundles 64 MiB, enrolment 8 KiB and other routes 16 KiB; a board file at its 16 MiB limit refuses every change with 413. Progress reports and heartbeats do not change the task revision.

On a linked computer the owner's /team/* requests are forwarded to the team server with the runner credential, and the owner-only local routes below drive execution; on the team server itself the same routes work in-process and linked is false.

Nothing here replays automatically: a restart, the recovery pass that runs every minute and POST /team-link/reconcile reconcile local attempt records with the team server and never start a run again. See team collaboration for roles, hand-overs, checkpoints and limits.

Explicit workers, coordination and extensions

Runs select SSH using loop.remoteWorker: {workerId,repoMapping}. Worker credentials stay on the provisioned worker; accepted turns are never retried automatically after a disconnected transport. See worker setup and receipt recovery. Coordination ships each repository separately; there is no atomic transaction across repositories. See coordinated changes. Extension installation is server configuration, not an HTTP operation; immutable version/hash pins are rechecked before execution. See trusted extension contracts.

Code-host review and publication

Owner-only GET /code-hosts lists configured GitLab/Bitbucket code adapters and safe operation receipts. POST /code-hosts/preview {integration,key,repo,project?} creates a short-lived server snapshot. POST /code-hosts/:id/fetch imports exact source/target Git objects without executing them; /:id/run accepts the prepared agent container and required verification configuration. /:id/review performs an explicit supported comment, reply, thread resolution or GitLab approval.

Push and merge each have distinct /:id/push-preview or /:id/merge-preview operations taking runId and an owned branch; their actions require the returned planId. POST /code-hosts/create-preview takes integration, runId, branch, targetBranch, title, and body; /:id/create explicitly creates the expected-absent source branch and native PR. An unknown receipt can only be acknowledged explicitly at /code-hosts/history/:id/acknowledge with {acknowledge:true}. No startup replay occurs.

Git updates use exact expected-ref leases. Merge is a pinned Git merge and may leave provider PR closure pending; native merge queues and atomic provider-policy snapshots are not claimed. Unsupported/unknown protected-branch policies fail closed. See provider-specific operations and limits.

GitHub threads use GET /runs/:id/pr-threads?branch=<owned-branch> and POST with {action:"load",snapshotId,threadId} or {action:"resolve",snapshotId,threadId,expectedHead,expectedRevision,resolved}. Resolution rechecks fresh remote state and reports postflight uncertainty. See thread pagination, permissions and mutation races.

Filesystem policies

Owner-only GET /projects/:id/filesystem-policy returns the committed policy. PUT accepts {revision,read:{allow,deny},write:{allow,deny}} with literal repository-relative paths. Policies intersect across matching projects and pinned run snapshots. App file/tree/search/write/diff access rechecks current rules; raw history and other unfilterable evidence are withheld. Custom restrictions pause ordinary application-managed execution globally, including background preparation. See activation, execution boundaries and HTTP error semantics.

Restricted execution uses a separate owner-only manual task surface:

The task container receives only permitted committed regular files and a new Git object database. It mounts no original repository metadata, host login directory, authentication volume or application memory. The image layer and copied files denied writes are read-only. Network starts off; enabling inference access is an explicit owner choice. Input/output limits are 500 files, 512 KiB per file and 16 MiB total; live monitoring is a polling safeguard, not a filesystem quota. Restarted effectful phases become unknown and require explicit inspection or cancellation. See runtime provisioning, recovery and limitations.

SSH projects

Owner-only connection management is available on the local listener. SSH host backends and phone/shared sessions cannot manage additional SSH connections.

The returned workspace uses the same local app origin and owner session. Its /computer/:id/api/ endpoints and event streams address the remote backend, so project paths, Git, files, checks, agent tools and terminals all refer to that server. Mutations are never replayed automatically. See SSH projects for setup, reconnection, remote previews, supported hosts and authentication boundaries.

Managed Tailscale certificates renew automatically while Tailscale remote access is enabled. GET /remote includes tls.renewal with automatic, running, nextAttempt, optional lastSuccess and a safe error. Renewal preserves paired sessions and control settings. Imported/environment certificates are excluded.

For multi-agent roles in Race, Debate, Review council, Supervisor and Loop workflows, a role setting can include additional models from the same provider: roleSettings.reviewers.claude = { model: "first", variants: [{ model: "second", effort: "low" }] }. Each entry runs separately with its own settings and session. Pipeline and other single-agent roles still use one model. Auto team pools also accept variants in roleSettings.pool: these are allowed model/effort choices for workers and reviewers. The coordinator selects among them within the member limit; it does not launch every selected model. Coordinator settings stay fixed. Additional models use the same validation as primary models (maximum 128 additional models per provider).

Result experiences and browser scenarios

These operations are owner-only and use the existing origin, authentication, filesystem-policy and host boundaries. New run requests can include intent (bug, feature, review, explore) and an existing same-repository journeyId. Comparison variants can include separate task instructions while sharing the base run configuration. Comparison launches can partially succeed; inspect the returned/visible group before retrying an interrupted request.

A replay receipt's passed status means only that the expected visible text appeared after the recorded interactions. It is separate from Git verification; see result experiences.

Documentation and help

GET /docs/ serves the bundled documentation without requiring a session; it contains only repository documentation. Page URLs use /docs/<guide>.html. Static files do not expose project state.

GET /api/docs-help lists installed built-in CLI providers for the authenticated owner. POST /api/docs-help invokes the selected CLI with documentation excerpts:

{
  "agent": "claude",
  "question": "How do I choose a workflow?",
  "page": "patterns",
  "settings": {"model": "sonnet"},
  "history": []
}

The response contains answer (plain text) and sources (guide IDs and titles). page is an optional guide ID; it is never a filesystem path. history accepts at most three {question,answer} pairs. The JSON body is limited to 64 KiB, questions to 4,000 characters and answers to 12,000. Settings accept a model and effort for the selected provider.

The endpoint is owner-only on the main listener, subject to the existing origin checks and filesystem execution policy. It does not support ACP, extension providers, repository paths or remote/container execution. Closing the request aborts the turn. Two help requests can run at once; extra requests return 429. See Local app help for execution and privacy boundaries.

Documentation library · Getting started · Local app help

Auto model catalog

GET /api/model-catalog returns provider discovery catalogs, managed-provider eligibility, allowResearch and offline status. It uses the cached catalog and performs bounded CLI discovery when missing or stale. POST /api/model-catalog explicitly refreshes; its closed body accepts optional booleans allowResearch and offline. Research is disabled by default. CODEFLOW_MODEL_NETWORK=offline prevents new discovery/research while retaining cached evidence.

Each catalog identifies its provider/environment/revision and separates reported model/effort availability, documented facts and run observations. It contains no authentication credentials. The existing /api/models endpoint retains its legacy behavior. Remote/container discovery happens in the selected execution environment, independently of this local preview. New Auto steps persist modelAssignment (provider, exact ID, effort, rationale, catalog revision/source and environment). Advanced worker roleSettings.pool pins are checked again at dispatch and on recovery; global coordinator defaults do not pin workers.

Antigravity execution authority

New run requests accept antigravityExecution: "isolated" | "native". Omission defaults to isolation, or inherits the parent's recorded choice for continuations. "native" explicitly opts into unrestricted host execution using the existing login and configuration; it leaves Claude/Codex permissions unchanged. An isolated parent cannot be upgraded by a child. Native mode rejects mandatory permission requirements, Safe/narrowed trust, tool approvals, remote/container and unattended/locked-down runs. It is not a template setting and is persisted in the run policy and step receipt.

GET /api/model-catalog?antigravityExecution=native and the POST refresh body's antigravityExecution choose native catalog discovery for previews; they do not grant execution authority. Default previews use isolated discovery. Both modes have distinct cache identities. Native execution records advisory read-only requests, unrestricted terminal access, provider-configured browser/MCP/hooks/native agents, and native child usage outside Code Flow's budget.