# zag run
Start an interactive agent session.
## Synopsis
zag [flags] run [prompt] [--resume <session-id> | --continue]
## Description
Starts a full interactive session with the selected agent. The agent's CLI takes over the terminal — you can type prompts, approve tool use, and have a back-and-forth conversation.
If a prompt is provided, it is sent as the first message. Otherwise the agent starts with an empty conversation.
When `--json` or `--json-schema` is combined with a prompt, the session runs non-interactively instead (equivalent to `exec`) to capture and validate the output.
Use `--resume <session-id>` to resume a specific session or `--continue` to resume the latest tracked session. The wrapper accepts either its own printed session ID or a native provider session ID.
## Arguments
prompt Optional initial prompt for the session
## Flags
All global flags apply (see `zag man zag`).
--resume <session-id> Resume a specific interactive session
--continue Resume the latest tracked interactive session
--session <UUID> Use a specific session ID (cannot combine with --resume/--continue)
--name <NAME> Human-readable session name (for discovery)
--description <TEXT> Short description of the session's purpose
--tag <TAG> Session tag for discovery (repeatable)
--context <SESSION_ID> Prepend the result of another session as context
--plan <PATH> Prepend a plan file (generated by `zag plan`) as context
--max-turns <N> Maximum number of agentic turns
--env <KEY=VALUE> Environment variable for the agent subprocess (repeatable)
--file <PATH> Attach a file to the prompt (repeatable)
--mcp-config <CONFIG> MCP server config: JSON string or path to a JSON file (Claude only)
--exit [<hint>] Capture the final result via `zag ps kill self <result>` (see Exit mode below)
## Exit mode
`--exit [<hint>]` augments the user prompt with instructions telling the agent to terminate the session by calling `zag ps kill self "<result>"` (or `zag ps kill self --file <path>`) once it has produced its result. This is the cost-free alternative to non-interactive `exec` mode for Claude (where `--print` now consumes API tokens — see `ZAG_CLAUDE_ALLOW_PRINT` in `zag man config`).
- The optional `<hint>` is a short human-readable description of the expected result. When non-empty, `zag ps kill` rejects empty results.
- Combine with `--json` to require the result to be valid JSON (validated at kill time).
- Combine with `--json-schema <SCHEMA>` to validate the result against a JSON schema.
- Validation failures reject the kill with a steering stderr message, so the agent can self-correct and call kill again.
- After a successful kill, the result is recorded as a `session_result` event in the session log and surfaced by `zag output <session>`.
`--exit` is only valid with `run`. Combining it with `exec` is rejected at parse time.
See [docs/exit-mode.md](../../docs/exit-mode.md) for the full reference, including how exit constraints survive auto-resume across upstream usage limits.
Example: run Claude interactively to compute a result without using `--print`.
zag -p claude run --exit "the sum" "what is 2+3"
# ...agent thinks, then runs: zag ps kill self "5"
zag output <session-id> # prints "5"
## Behavior
The agent subprocess inherits stdin, stdout, and stderr, giving you full interactive control. The wrapper displays initialization messages (model name, auto-approve status) unless `--quiet` is set.
After the session ends, agent resources are cleaned up. If a worktree was created (`--worktree`) and has no uncommitted changes, it is automatically removed. If there are changes, you are prompted whether to keep or remove it. If a sandbox was created (`--sandbox`), you are similarly prompted.
## Sandbox Mode
The `--sandbox` flag runs the agent inside a Docker sandbox microVM for stronger isolation than git worktrees. Docker sandboxes provide: microVM isolation, bidirectional workspace file sync, network policy enforcement, and transparent credential injection from host env vars.
zag --sandbox run Auto-named sandbox
zag --sandbox my-name run Named sandbox
Each provider maps to a Docker sandbox template (e.g., `docker/sandbox-templates:claude-code` for Claude). The agent binary and flags are passed through to the sandbox via `docker sandbox run ... -- <agent-flags>`.
`--sandbox` and `--worktree` are mutually exclusive.
After an interactive sandbox session, you are prompted whether to keep or remove the sandbox. Sandboxes can be resumed with `zag run --resume <session-id>`.
## Examples
zag run Start with default provider (Claude)
zag -p gemini run Interactive Gemini session
zag run "refactor the auth module" Start with an initial prompt
zag -w my-feature run Run in a named worktree
zag --sandbox run Run in a Docker sandbox
zag --sandbox my-sandbox run Named sandbox session
zag --model small run Use lightweight model for quick tasks
zag run --continue Resume the latest tracked session
zag run --resume abc-123 Resume a specific session
zag --session $(uuidgen) run Pre-set session ID for agent listen
zag run --name my-agent --tag backend Named and tagged session
zag -p ollama run Interactive Ollama session (qwen3.5:9b)
zag -p ollama --size 35b run Ollama with large model size
## See Also
zag man exec Non-interactive alternative