> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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.

```bash theme={null}
oz agent run [flags]
```

**Aliases:** `oz agent r`

### Flags

<ParamField path="--prompt" type="string">
  The prompt for the agent to carry out. Mutually exclusive with `--saved-prompt`.

  Short form: `-p`
</ParamField>

<ParamField path="--saved-prompt" type="string">
  The ID of a saved AI prompt to run. Mutually exclusive with `--prompt`.
</ParamField>

<ParamField path="--skill" type="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.
</ParamField>

<ParamField path="--model" type="string">
  Override the base model for this run. Use `oz model list` to see available model IDs.
</ParamField>

<ParamField path="--name" type="string">
  A human-readable name for this agent task.

  Short form: `-n`
</ParamField>

<ParamField path="--cwd" type="string">
  Working directory for the agent. Defaults to the current directory.

  Short form: `-C`
</ParamField>

<ParamField path="--environment" type="string">
  Cloud environment to use, identified by ID.

  Short form: `-e`
</ParamField>

<ParamField path="--mcp" type="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.
</ParamField>

<ParamField path="--computer-use" type="boolean">
  Enable computer use capabilities for this agent run. Mutually exclusive with `--no-computer-use`.
</ParamField>

<ParamField path="--no-computer-use" type="boolean">
  Disable computer use capabilities for this agent run. Mutually exclusive with `--computer-use`.
</ParamField>

<ParamField path="--conversation" type="string">
  Continue an existing cloud conversation by ID.
</ParamField>

<ParamField path="--profile" type="string">
  Agent profile ID to configure the terminal session.
</ParamField>

<ParamField path="--no-snapshot" type="boolean">
  Disable the end-of-run workspace snapshot upload.
</ParamField>

<ParamField path="--snapshot-upload-timeout" type="string">
  Maximum time to wait for the end-of-run snapshot upload (e.g. `5m`).
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
oz agent run-cloud [flags]
```

**Aliases:** `oz agent ra`, `oz agent run-ambient`

### Flags

<ParamField path="--prompt" type="string">
  The prompt for the agent to carry out. Mutually exclusive with `--saved-prompt`.

  Short form: `-p`
</ParamField>

<ParamField path="--saved-prompt" type="string">
  The ID of a saved AI prompt to run. Mutually exclusive with `--prompt`.
</ParamField>

<ParamField path="--skill" type="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.
</ParamField>

<ParamField path="--model" type="string">
  Override the base model for this run. Use `oz model list` to see available model IDs.
</ParamField>

<ParamField path="--name" type="string">
  A human-readable name for this agent task.

  Short form: `-n`
</ParamField>

<ParamField path="--environment" type="string">
  Cloud environment to run the agent in, identified by environment ID.

  Short form: `-e`
</ParamField>

<ParamField path="--no-environment" type="boolean">
  Run the agent without a cloud environment. Not recommended for most use cases.
</ParamField>

<ParamField path="--mcp" type="string">
  MCP server to start before executing the agent. Accepts a path to a JSON config file or inline JSON. Repeatable.
</ParamField>

<ParamField path="--computer-use" type="boolean">
  Enable computer use capabilities for this run.
</ParamField>

<ParamField path="--no-computer-use" type="boolean">
  Disable computer use capabilities for this run.
</ParamField>

<ParamField path="--open" type="boolean">
  Open the agent's session in Warp once it becomes available.
</ParamField>

<ParamField path="--conversation" type="string">
  Continue an existing cloud conversation by ID.
</ParamField>

<ParamField path="--attach" type="string">
  Path to a file to attach to the agent query. Repeatable — specify up to 5 times.
</ParamField>

<ParamField path="--host" type="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.
</ParamField>

<ParamField path="--no-snapshot" type="boolean">
  Disable the end-of-run workspace snapshot upload.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
oz agent list [flags]
```

### Flags

<ParamField path="--repo" type="string">
  List agent configurations from a specific GitHub repository. Format: `owner/repo` or `https://github.com/owner/repo`.

  Short form: `-r`
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
oz agent profile list
```