ak orchestrate start

Launch a new orchestrated run from a validated job graph file with fresh run ID, detached worker, process-group ownership, and durable readiness proof.

Use ak orchestrate start to validate a job graph file, generate a fresh opaque run ID, and spawn a detached worker that owns every job's process group for that run. The command blocks until the worker durably persists run state and proves readiness, then prints the run ID and initial status.

start always creates a new run; retrying the same graph does not reuse an existing run ID. Only ak orchestrate resume continues an existing run.

Usage

ak orchestrate start <job-graph.json>

Supply exactly one positional argument — the path to a JSON file describing the job graph. The file is validated before the worker is spawned; an invalid graph exits with code 1 and no run state is written.

Command flags

Shared flags (--json, --no-interactive, --quiet, --verbose, --yes) are described in CLI conventions. --json implies --no-interactive and returns a single-object envelope suitable for scripted run-id extraction.

Job graph validation

The graph file must supply, for each job:

id — opaque identifier unique within the graph.
command — the executable to run.
args — an argument array.
work_dir — the launch working directory.
env — an environment mapping.
depends_on — the ids of jobs that must complete first.

Validation is schema-strict. A malformed field, cycle in depends_on, or unknown job id rejects the graph before the worker is spawned.

Filesystem effects

On successful launch, the worker writes:

AGENTKIT_HOME/orchestrate/runs/<run-id>/state.json — durable run state.
AGENTKIT_HOME/orchestrate/runs/<run-id>/jobs/<job-id>/stdout.log and stderr.log — bounded per-job output.
AGENTKIT_HOME/orchestrate/runs/<run-id>/launch-graph.json — the exact graph digest bound to this run.
A control socket used by ak orchestrate status, ak orchestrate resume, and ak orchestrate stop.

The worker never persists prompts, raw argv, environment values, or secrets outside what the graph explicitly captures.

Human and JSON output

Human success prints the run ID and per-job initial status. --json returns:

{
  "action": "start",
  "run_id": "<opaque>",
  "graph_digest": "sha256:<hex>",
  "jobs": [
    { "id": "<job-id>", "state": "queued" }
  ]
}

Exit behavior

Exit	Meaning	Safe next step
`0`	The worker reached readiness and persisted run state.	Poll with `ak orchestrate status <run-id>`.
`1`	Job graph invalid, or the worker failed to reach readiness.	Correct the graph or inspect the reported reason; no run state was left behind on validation failure.
`2`	Flag parsing failed.	Correct the flags.
`3`	Interrupted before readiness.	Inspect `AGENTKIT_HOME/orchestrate/runs/` for a partial run; re-run when ready.
`6`	Platform unsupported (v1 requires Darwin).	Use a coordinator-owned subprocess on non-Darwin platforms.

Verify the launch

ak orchestrate status <run-id>

Reads the live worker's control socket to confirm the process group is alive under the same verified identity that start recorded.

On this page