oz agent — run and manage AI coding agents

Launch a local or cloud AI coding agent with oz agent run or run-cloud, list agent configurations, and manage agent profiles via subcommands.

The oz agent command is the entry point for running AI coding agents. Use oz agent run to launch an agent in your local terminal session, or oz agent run-cloud to dispatch a headless agent to a cloud environment. You can also list available agent configurations and manage agent profiles from this command group.

Synopsis

oz agent <subcommand> [flags]

Subcommands

Subcommand	Description
run	Run a new Oz agent in the local terminal
run-cloud	Dispatch an Oz agent that runs remotely in a cloud environment
list	List all available agent configurations
profile list	List available agent profiles

---

oz agent run

Runs a new Oz agent in your current terminal session. You must supply either --prompt or --saved-prompt (or --skill) to specify what the agent should do.

oz agent run [flags]

Aliases: oz agent r

Flags

--prompt · string

The prompt for the agent to carry out. Mutually exclusive with --saved-prompt.

Short form: -p

--saved-prompt · string

The ID of a saved AI prompt to run. Mutually exclusive with --prompt.

--skill · string

Use a skill as the base prompt for the agent. Format: skill_name, repo:skill_name, or org/repo:skill_name. Skills are searched in .agents/skills/, .warp/skills/, .claude/skills/, and .codex/skills/ directories. When combined with --prompt, the skill provides the base context and the prompt is the specific task.

--model · string

Override the base model for this run. Use oz model list to see available model IDs.

--name · string

A human-readable name for this agent task.

Short form: -n

--cwd · string

Working directory for the agent. Defaults to the current directory.

Short form: -C

--environment · string

Cloud environment to use, identified by ID.

Short form: -e

--mcp · string

MCP server to start before executing the agent. Accepts a path to a JSON config file or inline JSON. Repeatable — specify multiple times to include multiple servers.

--computer-use · boolean

Enable computer use capabilities for this agent run. Mutually exclusive with --no-computer-use.

--no-computer-use · boolean

Disable computer use capabilities for this agent run. Mutually exclusive with --computer-use.

--conversation · string

Continue an existing cloud conversation by ID.

--profile · string

Agent profile ID to configure the terminal session.

--no-snapshot · boolean

Disable the end-of-run workspace snapshot upload.

--snapshot-upload-timeout · string

Maximum time to wait for the end-of-run snapshot upload (e.g. 5m).

Examples

# Run an agent with a plain-text prompt
oz agent run --prompt "Add input validation to src/auth/login.ts"

# Use a saved prompt by ID
oz agent run --saved-prompt abc123

# Run with a specific model
oz agent run --prompt "Write unit tests for the auth module" --model claude-opus-4

# Use a skill as the base context and a prompt as the task
oz agent run --skill my-skill --prompt "Focus on the login form"

# Run in a specific working directory
oz agent run --prompt "Refactor the database layer" --cwd /path/to/repo

# Attach an MCP server from a config file
oz agent run --prompt "Analyse the database" --mcp ./mcp-config.json

# Continue an existing conversation
oz agent run --prompt "Now add error handling" --conversation conv_abc123

---

oz agent run-cloud

Dispatches an Oz agent to run headlessly in a cloud environment. The agent runs asynchronously — you do not need to keep your terminal open. Use oz run list and oz run get to check the results.

oz agent run-cloud [flags]

Aliases: oz agent ra, oz agent run-ambient

Flags

--prompt · string

The prompt for the agent to carry out. Mutually exclusive with --saved-prompt.

Short form: -p

--saved-prompt · string

The ID of a saved AI prompt to run. Mutually exclusive with --prompt.

--skill · string

Use a skill as the base prompt for the agent. Format: repo:skill_name or org/repo:skill_name. The skill is resolved at runtime in the agent’s cloud environment.

--model · string

Override the base model for this run. Use oz model list to see available model IDs.

--name · string

A human-readable name for this agent task.

Short form: -n

--environment · string

Cloud environment to run the agent in, identified by environment ID.

Short form: -e

--no-environment · boolean

Run the agent without a cloud environment. Not recommended for most use cases.

--mcp · string

MCP server to start before executing the agent. Accepts a path to a JSON config file or inline JSON. Repeatable.

--computer-use · boolean

Enable computer use capabilities for this run.

--no-computer-use · boolean

Disable computer use capabilities for this run.

--open · boolean

Open the agent’s session in Warp once it becomes available.

--conversation · string

Continue an existing cloud conversation by ID.

--attach · string

Path to a file to attach to the agent query. Repeatable — specify up to 5 times.

--host · string

Where the job should be hosted. Set to warp (or omit) to run on Warp’s infrastructure. Any other value is matched against a self-hosted worker name.

--no-snapshot · boolean

Disable the end-of-run workspace snapshot upload.

Examples

# Dispatch a cloud agent with a prompt
oz agent run-cloud --prompt "Triage and label open GitHub issues" --environment env_abc123

# Run without a pre-created environment
oz agent run-cloud --prompt "Run the test suite" --no-environment

# Use a skill from a GitHub repo
oz agent run-cloud --skill owner/my-repo:weekly-review --environment env_abc123

# Attach an image to the agent query
oz agent run-cloud \
  --prompt "Fix the layout issue shown in this screenshot" \
  --attach ./screenshot.png \
  --environment env_abc123

# Open the session in Warp when it's ready
oz agent run-cloud --prompt "Investigate the memory leak" --environment env_abc123 --open

---

oz agent list

Lists all available agent configurations, optionally scoped to a specific GitHub repository.

oz agent list [flags]

Flags

--repo · string

List agent configurations from a specific GitHub repository. Format: owner/repo or https://github.com/owner/repo.

Short form: -r

Examples

# List all available agent configurations
oz agent list

# List configurations from a specific repository
oz agent list --repo my-org/my-repo

---

oz agent profile list

Lists available agent profiles that can be used to configure the terminal session for an agent run.

oz agent profile list