Skip to main content
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

SubcommandDescription
runRun a new Oz agent in the local terminal
run-cloudDispatch an Oz agent that runs remotely in a cloud environment
listList all available agent configurations
profile listList 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

Build docs developers (and LLMs) love

Get started for freeTalk to us