Add project
POST /api/v1/projects
Registers a host directory as a Warden project. Optionally creates a container in the same request by including a “container” field. If container creation fails, the project is cleaned up automatically.
Request Body required
Section titled “Request Body required ”Project details (with optional container config)
object
Project details (with optional container config)
object
AgentType selects the CLI agent to run (e.g. “claude-code”, “codex”). Defaults to “claude-code” if omitted.
CloneURL is the git repository URL to clone inside the container. Required for remote projects; must be empty when ProjectPath is set.
Container holds optional container configuration. When provided, a container is created as part of the same request.
object
AgentType identifies the CLI agent running in this project (e.g. “claude-code”, “codex”).
AllowedDomains lists domains accessible when NetworkMode is “restricted”.
CloneURL is the git repository URL to clone inside the container (remote projects).
CostBudget is the per-project cost limit in USD (0 = use global default).
EnabledAccessItems lists active access item IDs (e.g. [“git”,“ssh”]).
EnabledRuntimes lists active runtime IDs (e.g. [“node”,“python”,“go”]).
object
ForwardedPorts lists container ports to expose via the reverse proxy. Each port (1-65535) is accessible at http://{projectId}-{agentType}-{port}.localhost:{serverPort}/
Mounts is a list of additional bind mounts from host into the container.
object
ContainerPath is the absolute path inside the container.
HostPath is the absolute path on the host.
ReadOnly mounts the path as read-only inside the container.
NetworkMode controls the container’s network isolation level.
SkipPermissions controls whether terminals skip permission prompts. Stored as a Docker label on the container.
Temporary is true when a remote project’s workspace is ephemeral.
Name is an optional container name override.
ProjectPath is the absolute host directory to register as a project. Required for local projects; must be empty when CloneURL is set.
Temporary is true when a remote project’s workspace should be ephemeral (container layer only, lost on recreate). Ignored for local projects.
Responses
Section titled “ Responses ”Created
object
Container holds the container result when a container was created. Nil when the request did not include container configuration.
object
AgentType is the agent type for this container.
ContainerID is the Docker container ID.
Name is the container name.
ProjectID is the deterministic project identifier.
Recreated is true when the container was fully recreated (not just settings updated).
Project holds the registered project result.
object
AgentType is the agent type for this project (e.g. “claude-code”, “codex”).
ContainerID is the Docker container ID, when available.
Name is the user-chosen project display name.
ProjectID is the deterministic project identifier.
Bad Request
object
Container name already in use
object
Internal Server Error