Skip to main content
POST
/
agents
/
deploy
Deploy Agent
curl --request POST \
  --url https://api.example.com/agents/deploy \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "<string>",
  "author_email": "<string>",
  "author_name": "<string>",
  "branch": "<string>",
  "git_hash": "<string>",
  "image_url": "<string>",
  "acp_type": "async",
  "are_tasks_sticky": true,
  "description": "<string>",
  "git_message": "<string>",
  "is_dirty": false,
  "replicas": 1,
  "resources": {},
  "sdk_type": "claude_agent_sdk",
  "source_filesystem_id": "<string>"
}
'
{
  "agent_id": "<string>",
  "branch_id": "<string>",
  "message": "<string>",
  "version_id": "<string>",
  "version_status": "DEPLOYING",
  "tasks_migrated": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.terminaluse.com/llms.txt

Use this file to discover all available pages before exploring further.

The deployment is asynchronous. After calling this endpoint, poll GET /branches/{branch_id} for status updates until status is READY or FAILED.

Body

application/json

Request model for deploying an agent.

Called by CLI after pushing the container image to the registry.

​
agent_name
string
required

Agent name in 'namespace_slug/agent_name' format (lowercase alphanumeric, hyphens, underscores)

Pattern: ^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_-]*$
​
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')

​
git_hash
string
required

Git commit hash (short or full)

Required string length: 7 - 40
​
image_url
string
required

Full container image URL (e.g., 'us-east4-docker.pkg.dev/proj/repo/agent:hash')

​
acp_type
enum<string>
default:async

ACP server type (sync or async)

Available options:
sync,
async
​
are_tasks_sticky
boolean | null

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.

​
description
string | null

Agent description (used when creating new agent)

​
git_message
string | null

Git commit message (truncated if too long)

Maximum string length: 500
​
is_dirty
boolean
default:false

Whether the working directory had uncommitted changes at deploy time

​
replicas
integer
default:1

Desired replica count (1-10)

Required range: 1 <= x <= 10
​
resources
Resources · object

Resource requests and limits (e.g., {'requests': {'cpu': '100m', 'memory': '256Mi'}, 'limits': {'cpu': '1000m', 'memory': '1Gi'}})

​
sdk_type
enum<string>
default:claude_agent_sdk

SDK type for agent runtime

Available options:
claude_agent_sdk,
codex_agent_sdk
​
source_filesystem_id
string | null

Filesystem snapshot containing the deploy source for Builder reopenability

Response

Successful Response

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

​
version_id
string
required

New version ID

​
version_status
enum<string>
required

Initial version status

Available options:
DEPLOYING,
ACTIVE,
FAILED,
UNHEALTHY,
DRAINING,
RETIRED,
ROLLED_BACK
​
tasks_migrated
integer | null

Number of tasks migrated from old version (if any)