---
title: "Provision an agent and its runtime in one call"
method: POST
path: "/v1/runtimes/provision"
tags: ["Runtimes"]
---

# Provision an agent and its runtime in one call

`POST /v1/runtimes/provision`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/runtimes/provision`
- Auth: HTTP bearer

Creates (or reuses) the agent, its keys and default-vault grant, the runtime, and
starts it. Each step runs the same code as the individual endpoints, so the
`agent.create` consensus gate, plan caps, image allowlist and included-slot logic
apply exactly as one click at a time. Human-only. The new agent's API key is
returned once.

## Request body

- object
  - `name` string, required
  - `template` string
  - `preset` string
  - `agent` object, required: Either `id` (existing) or `name` (create).
    - `id` string, uuid
    - `name` string
    - `description` string
  - `env_public` object
  - `expose_http` boolean
  - `source_repo` string
  - `startup_command` string
  - `environment` string
  - `start` boolean
  - `approval_id` string, uuid

## Response `201`

Provisioned

- object
  - `runtime` RuntimeResponse, required
    - `previous_image_digest` string, nullable
    - `image_digest` string, nullable: Resolved image (digest form when the provider reports one); runtime-minted agent tokens carry it as `runtime_image`, which access policies can require via `conditions.runtime_image_in`.
    - `schedule` object, nullable
    - `next_scheduled_start_at` string, date-time, nullable
    - `scheduled_stop_at` string, date-time, nullable
    - `id` string, uuid, required
    - `name` string, required
    - `agent_id` string, uuid, required
    - `template` string, nullable
    - `preset` string, nullable
    - `provider` string, nullable
    - `status` 'creating' | 'running' | 'stopping' | 'stopped' | 'failed' | 'deleting', required
    - `image` string, nullable
    - `environment` string, nullable: Vault environment for env var resolution
    - `env_public` object, nullable
    - `idle_timeout_secs` integer, nullable
    - `expose_http` boolean, nullable
    - `slug` string, nullable
    - `public_url` string, nullable
    - `http_port` integer, nullable
    - `inbound_auth` 'api_key' | 'jwt' | 'public', nullable
    - `shell_access_enabled` boolean
    - `shell_auth_policy` string
    - `shell_max_session_minutes` integer
    - `monthly_hours_used` number, nullable
    - `has_paid_addon` boolean: Whether this runtime has a paid Stripe add-on (unlimited hours).
    - `billing_kind` 'pool' | 'included' | 'addon': `pool` — counts against the plan's monthly runtime hours. `included` — the plan's free runtime (every plan from Pro up includes one small or medium runtime, no hour cap, no charge). `addon` — paid Stripe subscription item (no hour cap).
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `agent_id` string, uuid, required
  - `agent_api_key` string: Only when the agent was created here; shown once.
  - `vault_id` string, uuid
  - `started` boolean, required

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)