# Deploy a managed agent from a template or listing

`POST /v1/agents`

**In this build:** Works on the simulator or a real VM.

**Scope:** `platform.write`

**CLI:** `harebox agent new`

Send an `Idempotency-Key` header. A retry with the same key never repeats the action.

## Request: `CreateAgentRequest`

| Field | Type | Notes |
|---|---|---|
| `name` | `string` |  |
| `listing` | `string` | A marketplace listing to deploy, such as lst_harebox_coding. |
| `template` | `string` | One of your templates, name@version or a share code. Ignored with a listing. |
| `harness` | `string` |  |
| `model` | `string` |  |
| `instructions` | `string` |  |
| `size` | `Size` |  |
| `wake` | `AgentWake` |  |
| `end_user` | `string` | Your external ID for the person this agent serves. Created with no policy if new. |
| `env` | `object` |  |
| `labels` | `Labels` |  |
| `project` | `string` |  |

## Response: 201

`Agent`

| Field | Type | Notes |
|---|---|---|
| `id` (required) | `string` |  |
| `name` | `string` |  |
| `sandbox` (required) | `string` | Its agent-mode sandbox. Every sandbox operation works on it. |
| `state` (required) | `LifecycleState` |  |
| `harness` (required) | `string` |  |
| `model` | `string` |  |
| `instructions` | `string` | Written to AGENTS.md and CLAUDE.md in its home directory. |
| `end_user` | `string or null` | Your external ID for the person this agent serves. |
| `listing` | `string or null` |  |
| `template` | `string or null` |  |
| `publisher` | `string or null` |  |
| `price_usd_month` | `number` | A paid listing's price per agent-month, charged daily from the wallet. 0 when free. |
| `size` | `object` |  |
| `wake` | `AgentWake` |  |
| `messages` | `integer` |  |
| `created_at` (required) | `string` |  |
| `deleted_at` | `string or null` |  |

Errors follow [one format](../errors.html).