---
title: "Deploy Agent"
method: POST
path: "/agents/deploy"
tags: ["Branches", "Agents"]
---

# Deploy Agent

`POST /agents/deploy`

Deploy an agent to the platform.

    Called by CLI after pushing the container image to the registry.
    Creates or updates agent, branch, and version records.

    The deployment is asynchronous - poll GET /branches/{branch_id}
    for status updates until status is READY or FAILED.

    **Flow:**
    1. CLI builds and pushes image to registry (using /registry/auth)
    2. CLI calls POST /agents/deploy with image details
    3. Platform creates records and triggers K8s deployment
    4. Container starts and calls POST /versions/register
    5. CLI polls GET /branches/{id} for status

## Request body

- DeployRequest — Request model for deploying an agent. Called by CLI after pushing the container image to the registry.
  - `acp_type` 'sync' | 'async' — Type of ACP server.
  - `agent_name` string, required — Agent name in 'namespace_slug/agent_name' format (lowercase alphanumeric, hyphens, underscores)
  - `are_tasks_sticky` boolean, nullable — If true, running tasks stay on their original version until completion during this deploy. If false or None, tasks are migrated to the new version immediately.
  - `author_email` string, required — Git commit author email
  - `author_name` string, required — Git commit author name
  - `branch` string, required — Git branch name (e.g., 'main', 'feature/new-tool')
  - `description` string, nullable — Agent description (used when creating new agent)
  - `git_hash` string, required — Git commit hash (short or full)
  - `git_message` string, nullable — Git commit message (truncated if too long)
  - `image_url` string, required — Full container image URL (e.g., 'us-east4-docker.pkg.dev/proj/repo/agent:hash')
  - `is_dirty` boolean — Whether the working directory had uncommitted changes at deploy time
  - `replicas` integer — Desired replica count (1-10)
  - `resources` object, nullable — Resource requests and limits (e.g., {'requests': {'cpu': '100m', 'memory': '256Mi'}, 'limits': {'cpu': '1000m', 'memory': '1Gi'}})
  - `sdk_type` 'claude_agent_sdk' | 'codex_agent_sdk' — SDK type for agent runtime.
  - `source_filesystem_id` string, nullable — Filesystem snapshot containing the deploy source for Builder reopenability

## Response `201`

Successful Response

- DeployResponse — Immediate response from deploy request. CLI polls GET /branches/{branch_id} or GET /versions/{version_id} for status updates.
  - `agent_id` string, required — Agent ID (created or existing)
  - `branch_id` string, required — Branch ID for this git branch
  - `message` string, required — Human-readable status message
  - `tasks_migrated` integer, nullable — Number of tasks migrated from old version (if any)
  - `version_id` string, required — New version ID
  - `version_status` 'DEPLOYING' | 'ACTIVE' | 'FAILED' | 'UNHEALTHY' | 'DRAINING' | 'RETIRED' | 'ROLLED_BACK', required — Status of a version in its lifecycle.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/terminaluse/apis/sb0-api.md) · [All operations](https://skmtc.net/terminaluse/apis/sb0-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/terminaluse/sb0-api/revisions/f24a474dc415/schema)