Developer Mode

vagaris dev is the CLI execution broker. Instead of the server spawning an agent on its own host, your machine claims a queued run, has the server verify the lease it was given, and executes the coding agent locally — in an isolated git worktree, with the tool allowlist the lease permits, producing evidence the server can audit.

vagaris dev --agent-id <agent-id> --run-id <run-id> --company-id <company-id>

--agent-id and --run-id are required; the run must be queued. --company-id is required too, from the flag, VAGARIS_COMPANY_ID, or the active context profile.

What happens, in order

1. Claim. POST /cli/claim with the agent, run, optional issue and scope, the adapter type and the node id. The server's act gate decides. A refusal ends the command with exit code 2 and the reason.
2. Verify. The CLI holds no signing secret. It sends the lease back — POST /cli/claim/<leaseId>/verify with --node-id if given — and nothing below this line runs unless the server says the lease is valid. A node-bound lease presented from another node is refused here.
3. Act envelope. The lease's act axes are materialised into an envelope: tier (autonomous, supervised, propose_only), scopes (where the run may act) and tools (what it may execute). A lease with no tool policy materialises as none, which is a refusal — the default is deny. See Permissions.
4. Executor. The adapter type is resolved through the CLI-hosted executor registry. claude-local runs claude, codex-local runs codex; any other adapter is refused because the CLI cannot derive an allowlist for it. See Executors.
5. Worktree. A git worktree is created for this run inside the repository you ran the command from, so concurrent runs cannot see each other's changes. Skip with --no-worktree. Outside a git repository the run proceeds without isolation.
6. Baseline. Before the agent starts, the repository's baseline gates run on the clean worktree. A gate that already fails is recorded as pre-existing so the run is not blamed for it. Skip with --no-baseline.
7. Session envelope. With --agent or --native, the server session (organization, repository, authority, budget, model policy, evidence requirements, run lineage) is serialised once, deterministically, and passed to the agent through the VAGRIS_SESSION_ENVELOPE environment variable. --agent marks it delegated; --native marks it native; the two envelopes are otherwise byte-identical.
8. Governance chain. The spawn is routed through the governed-spawn resolver, which decides whether the executor runs governed or exits with a code and reason.
9. Environment sanitising. Your shell environment is scrubbed before the agent sees it: product variables, LD_*/DYLD_*, NODE_OPTIONS and other interpreter hooks, infrastructure write tokens and seat-forbidden secrets are stripped. The report lists strippedEnvKeys.
10. Spawn. The executor binary runs with the lease-derived allowlist — for Claude Code that is claude --allowedTools <list>, never claude --dangerously-skip-permissions. Its stdout and stderr stream to your terminal and are collected as evidence.
11. Evidence and closure. Session boundaries, policy decisions, baseline probes, the command and its exit code are recorded; the closure-evidence gate evaluates the envelope. The worktree is removed whether the run succeeded or not.

Flags

Flag	Effect
-a, --agent-id <agentId>	Agent whose run to claim (required)
-r, --run-id <runId>	Queued heartbeat run to claim (required)
-i, --issue-id <issueId>	Issue being worked, if any
--scope <scope>	Scope the CLI is working in, if known
--adapter <type>	Executor adapter; default claude-local
--node-id <id>	Node id to present, for a node-bound lease (see Node Enrolment)
--agent	Delegated agent mode: hand the native frontend a session envelope with delegated=true
--native	Same envelope, delegated=false
--no-spawn	Resolve claim, lease, envelope and governance decision, but do not execute the child
--no-worktree	Do not create an isolated per-run worktree
--no-baseline	Skip the pre-run baseline capture

Plus the shared client options (--api-base, --api-key, --context, --profile, --config, --data-dir, --json, -C, --company-id).

Reading the report

dev always prints a JSON report. The fields worth checking first:

• claimed, refused, reason — did the server let this run proceed, and if not why.
• leaseVerified — false means step 2 refused; nothing was spawned.
• envelope.tier, envelope.actTools — what the agent was permitted.
• worktree.path, baseline.preExistingFailures.
• governance.governed, spawn.executed, spawn.exitCode.
• strippedEnvKeys — variables withheld from the agent.
• evidence.itemCount, closureGate — what was recorded and whether it satisfied the closure gate.

Exit code is 2 for any refusal (act gate, lease, deny-default tools, unknown executor), the governance chain's own code when it exits, 1 when the executor exited non-zero, and 0 otherwise.

Dry run

To see the full decision without executing anything:

vagaris dev --agent-id <agent-id> --run-id <run-id> --no-spawn --json

The report shows the command and arguments that would have run.

Controlling the run while it executes

From another terminal, vagaris runctl operates on the same run id:

vagaris runctl status --run-id <run-id>
vagaris runctl attach --run-id <run-id>
vagaris runctl pause --run-id <run-id> --reason "checking output"
vagaris runctl resume --run-id <run-id>
vagaris runctl cancel --run-id <run-id>

pause parks the run at paused (stop-and-continue, not a freeze; the session identity survives so resume continues rather than restarts) and only works on queued, running or scheduled_retry runs. cancel goes through the kill-switch integrity gate: if the process is still alive after the kill attempt the run is not reported cancelled — the CLI shows the true status. --no-wait skips polling for the verdict; --kill-switch-timeout <ms> (default 10000) bounds the wait.

When the agent needs something outside its lease, it asks the server rather than the CLI deciding locally — Permissions covers runctl scope-request and runctl privileged.