Create container

POST

/api/v1/projects/{projectId}/{agentType}/container

• Local development server

Creates a new container for the given project with the provided configuration. Supports network isolation modes and custom bind mounts.

Parameters

Path Parameters

projectId

required

string

Project ID

Request Body ^required

Container configuration

One of:

object

object

object

Container configuration

object

agentType

AgentType identifies the CLI agent running in this project (e.g. “claude-code”, “codex”).

string

Allowed values: claude-code codex claude-code

allowedDomains

AllowedDomains lists domains accessible when NetworkMode is “restricted”.

Array<string>

cloneURL

CloneURL is the git repository URL to clone inside the container (remote projects).

string

costBudget

CostBudget is the per-project cost limit in USD (0 = use global default).

number

enabledAccessItems

EnabledAccessItems lists active access item IDs (e.g. [“git”,“ssh”]).

Array<string>

enabledRuntimes

EnabledRuntimes lists active runtime IDs (e.g. [“node”,“python”,“go”]).

Array<string>

envVars

object

key

additional properties

string

forwardedPorts

ForwardedPorts lists container ports to expose via the reverse proxy. Each port (1-65535) is accessible at http://{projectId}-{agentType}-{port}.localhost:{serverPort}/

Array<integer>

image

string

mounts

Mounts is a list of additional bind mounts from host into the container.

Array<object>

object

containerPath

ContainerPath is the absolute path inside the container.

string

hostPath

HostPath is the absolute path on the host.

string

readOnly

ReadOnly mounts the path as read-only inside the container.

boolean

name

string

networkMode

NetworkMode controls the container’s network isolation level.

string

Allowed values: full restricted none

projectPath

string

skipPermissions

SkipPermissions controls whether terminals skip permission prompts. Stored as a Docker label on the container.

boolean

temporary

Temporary is true when a remote project’s workspace is ephemeral.

boolean

Responses

201

Created

Container holds the container result when a container was created. Nil when the request did not include container configuration.

object

agentType

AgentType is the agent type for this container.

string

containerId

ContainerID is the Docker container ID.

string

name

Name is the container name.

string

projectId

ProjectID is the deterministic project identifier.

string

recreated

Recreated is true when the container was fully recreated (not just settings updated).

boolean

400

Bad Request

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string

404

Not Found

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string

409

Container name already in use

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string

500

Internal Server Error

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string