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 wrapped JSON envelope (kind plus data) 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 under AGENTKIT_HOME/orchestrate/runs/<run-id>/:

state.json — durable run state.
output-<job-id>.log — bounded redacted merged output per job.
events.jsonl — bounded observation journal.
graph.json — private launch graph; may contain argv and environment.
A control socket used by ak orchestrate status, ak orchestrate resume, and ak orchestrate stop.

The launch graph retains argv and environment for recovery. Keep credentials out of job specs, and exclude invocation files from diagnostic exports.

Human and JSON output

Human success prints the run ID and per-job initial status. --json wraps a runVM as kind: "orchestrate.start":

{
  "schema_version": 1,
  "kind": "orchestrate.start",
  "data": {
    "run_id": "<opaque>",
    "status": "<run-status>",
    "all_settled": false,
    "revision": 0,
    "events_truncated": false,
    "status_counts": { "queued": 1 },
    "jobs": [
      {
        "job_id": "<job-id>",
        "status": "queued",
        "route_source": "declared-in-graph",
        "output_bytes": 0,
        "output_truncated": false
      }
    ]
  }
}

Do not parse a top-level action or job id/state pair. The envelope carries data.run_id, data.all_settled, and per-job job_id/status.

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