---
title: "Create a sandbox in a workspace"
method: POST
path: "/api/workspaces/{wid}/sandboxes"
tags: ["Sandboxes"]
---

# Create a sandbox in a workspace

`POST /api/workspaces/{wid}/sandboxes`

Validates type / CPU / memory / idle_timeout / quota / budget. Returns 201 immediately with status="provisioning"; container starts asynchronously.

## Path parameters

- `wid` string, required

## Request body

- SandboxCreateRequest
  - `cpu` integer — optional; millicores, e.g. 500 or 2000
  - `idle_timeout` integer — optional; seconds
  - `memory` integer — optional; bytes, e.g. 536870912 (512Mi)
  - `metadata` object — optional; arbitrary key-value metadata
  - `name` string, required
  - `type` string — optional; default "opencode"

## Response `201`

Created

- Sandbox
  - `agent_info` AgentInfo
    - `agent_version` string, required
    - `cpu_count_logical` integer, required
    - `cpu_model_name` string, required
    - `disk_free` integer, required
    - `disk_total` integer, required
    - `hostname` string, required
    - `kernel_arch` string, required
    - `memory_total` integer, required
    - `opencode_version` string, required
    - `os` string, required
    - `platform` string, required
    - `platform_version` string, required
    - `updated_at` string, required
    - `workdir` string, required
  - `claudecode_url` string
  - `cpu` integer
  - `created_at` string, required
  - `custom_url` string
  - `id` string, required
  - `idle_timeout` integer
  - `im_bindings` IMBinding[]
    - `bot_id` string, required
    - `bound_at` string, required
    - `provider` string, required
    - `user_id` string
  - `is_local` boolean, required
  - `jupyter_url` string
  - `last_activity_at` string, nullable
  - `last_heartbeat_at` string
  - `memory` integer
  - `metadata` object
  - `name` string, required
  - `openclaw_url` string
  - `opencode_url` string
  - `paused_at` string, nullable
  - `short_id` string
  - `status` string, required
  - `type` string, required
  - `weixin_bindings` IMBinding[]
    - `bot_id` string, required
    - `bound_at` string, required
    - `provider` string, required
    - `user_id` string
  - `workspace_id` string, required

## Other responses

- `400` — validation error (type/cpu/memory/idle_timeout)
- `403` — insufficient role / quota / budget
- `500` — internal error

---

[API](https://skmtc.dev/agentserver/apis/agentserver-api.md) · [All operations](https://skmtc.dev/agentserver/apis/agentserver-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentserver/agentserver-api/revisions/e8c329825b4e/schema)