Deploy & Version Commands

This section covers all CLI commands for deploying and managing versions of your AI agents on Agent Cloud.

Deploy

Create a new version of your agent on VideoSDK cloud.

Usage

videosdk agent deploy [NAME] [OPTIONS]

Arguments

Argument	Required	Description
`NAME`	No	Optional version name

Options

Option	Short	Description	Default
`--image`	`-i`	Docker image URL (e.g., `myrepo/myagent:v1`)	From `videosdk.yaml`
`--version-tag`		Version tag (e.g., `main/0.0.2`)	None
`--min-replica`		Minimum number of replicas	`0`
`--max-replica`		Maximum number of replicas	`3`
`--profile`		Compute profile: `cpu-small`, `cpu-medium`, `cpu-large`	`cpu-small`
`--agent-id`		Agent ID	From `videosdk.yaml`
`--deployment-id`		Deployment ID	From `videosdk.yaml`
`--env-secret`		ID of the environment secret set to use	None
`--image-pull-secret`		Name of the image pull secret for private registries	None
`--region`		Deployment region (e.g., `in002`, `us002`)	`us002`

note

In examples like myrepo/myagent:v1, myrepo is a placeholder for your Docker registry username (e.g., your Docker Hub username).

Example Output

$ videosdk agent deploy --image myrepo/myagent:v1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Creating Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Version Name    my-agent's version
  Agent ID        abc123xyz
  Deployment ID   dep-456
  Image           myrepo/myagent:v1

────────────────────────────────────────

⠋ Creating Version...

✓ Version created successfully for agent: abc123xyz
  Version ID    ver-789

ℹ Next step: Check version status
  videosdk agent version status -v ver-789

Examples

# Basic deployment
videosdk agent deploy --image myrepo/myagent:v1

# Named version with version tag
videosdk agent deploy my-version --image myrepo/myagent:v1 --version-tag main/0.0.1

# Deployment with secrets and custom profile
videosdk agent deploy --image myrepo/myagent:v1 --env-secret my-secrets --profile cpu-medium

# Deployment to specific region
videosdk agent deploy --image myrepo/myagent:v1 --region in002

List

List all versions for an agent deployment.

Usage

videosdk agent version list [OPTIONS]

Options

Option	Description	Default
`--agent-id`	Agent ID	From `videosdk.yaml`
`--deployment-id`	Deployment ID	From `videosdk.yaml`
`--page`	Page number	`1`
`--per-page`	Items per page	`10`
`--sort`	Sort order: `1` (oldest first) or `-1` (newest first)	`-1`

Example Output

$ videosdk agent version list

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Listing Versions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Agent ID        abc123xyz
  Deployment ID   dep-456

┌────────────┬─────────┬──────────┬────────────┬─────────────┐
│ Version ID │ Status  │ Region   │ Profile    │ Replicas    │
├────────────┼─────────┼──────────┼────────────┼─────────────┤
│ ver-001    │ active  │ us002    │ cpu-small  │ 2/5         │
│ ver-002    │ inactive│ in002    │ cpu-medium │ 0/10        │
└────────────┴─────────┴──────────┴────────────┴─────────────┘

Examples

# List all versions
videosdk agent version list

# List versions for specific agent
videosdk agent version list --agent-id abc123

# Paginated listing
videosdk agent version list --page 2 --per-page 20

# Sort oldest first
videosdk agent version list --sort 1

Update

Update an existing version configuration.

Usage

videosdk agent version update [OPTIONS]

Options

Option	Short	Description	Required
`--version-id`	`-v`	Version ID to update	Yes
`--min-replica`		New minimum replicas	No
`--max-replica`		New maximum replicas	No
`--profile`		New compute profile	No
`--image-pull-secret`		New image pull secret name	No
`--env-secret`		New environment secret name	No

Example Output

$ videosdk agent version update -v ver123 --min-replica 3 --max-replica 15

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Updating Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Min Replicas    3
  Max Replicas    15

⠋ Updating Version...

✓ Version updated successfully

Examples

# Update replica counts
videosdk agent version update -v ver123 --min-replica 2 --max-replica 10

# Update to larger profile
videosdk agent version update -v ver123 --profile cpu-large

# Update environment secrets
videosdk agent version update -v ver123 --env-secret new-secrets

Activate

Activate a version to start receiving traffic.

Usage

videosdk agent version activate [OPTIONS]

Options

Option	Short	Description	Required
`--version-id`	`-v`	Version ID to activate	Yes

Example Output

$ videosdk agent version activate -v ver123

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Activating Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⠋ Activating Version...

✓ Version activated successfully

Deactivate

Deactivate a version to stop receiving new traffic.

Usage

videosdk agent version deactivate [OPTIONS]

Options

Option	Short	Description	Required
`--version-id`	`-v`	Version ID to deactivate	Yes
`--force`		Force deactivate even with active sessions	No

Example Output

$ videosdk agent version deactivate -v ver123

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Deactivating Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⠋ Deactivating Version...

✓ Version deactivated successfully

Examples

# Graceful deactivation
videosdk agent version deactivate -v ver123

# Force deactivation (terminates active sessions)
videosdk agent version deactivate -v ver123 --force

Status

Get the current status of a version.

Usage

videosdk agent version status [OPTIONS]

Options

Option	Short	Description	Required
`--version-id`	`-v`	Version ID to check	Yes

Example Output

$ videosdk agent version status -v ver123

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Getting Version Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Version ID      ver123
  Status          active
  Replicas        3/5 running
  Health          healthy

ℹ Next step: Start a session
  videosdk agent session start -v ver123

Describe

Get detailed information about a version.

Usage

videosdk agent version describe [OPTIONS]

Options

Option	Short	Description	Required
`--version-id`	`-v`	Version ID to describe	Yes

Example Output

$ videosdk agent version describe -v ver123

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Describing Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Version ID        ver123
  Agent ID          abc123xyz
  Deployment ID     dep-456
  Status            active
  Image             myrepo/myagent:v1
  Profile           cpu-medium
  Min Replicas      2
  Max Replicas      10
  Current Replicas  5
  Region            in002
  Created At        2026-01-15 10:30:00

Quick Reference

Command	Description
`videosdk agent deploy`	Create a new version
`videosdk agent version list`	List all versions
`videosdk agent version update`	Update version config
`videosdk agent version activate`	Activate a version
`videosdk agent version deactivate`	Deactivate a version
`videosdk agent version status`	Get version status
`videosdk agent version describe`	Get detailed version info

videosdk.yaml Reference

You can configure your entire deployment process in the videosdk.yaml file. This allows you to run commands like videosdk agent build, videosdk agent push, and videosdk agent deploy without providing extra flags.

agent:
  id: ag_xxxxxx # automatically generated
  name: agent-test # automatically generated, if not provided in videosdk agent init
build:
  image: username/myagent:v1 # docker image
  logs:
    id: b_xxxxxx # automatically generated
    enabled: true # build logs enabaled or not
deploy:
  id: dep_xxxxxx # automatically generated
  replicas:
    min: 0
    max: 3
  profile: cpu-small
  region: us002 # options: in002, us002
secrets:
  env: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # env secrets, global
  image-pull: image-pull-secret-name # image pull secrets for private images, region specific

Next Steps

Learn about managing enironment secrets or image pull secrets for your deployments
View sessions for your agents

Got a Question? Ask us on discord

Deploy​

Usage​

Arguments​

Options​

Example Output​

Examples​

List​

Usage​

Options​

Example Output​

Examples​

Update​

Usage​

Options​

Example Output​

Examples​

Activate​

Usage​

Options​

Example Output​

Deactivate​

Usage​

Options​

Example Output​

Examples​

Status​

Usage​

Options​

Example Output​

Describe​

Usage​

Options​

Example Output​

Quick Reference​

videosdk.yaml Reference​

Next Steps​

Deploy

Usage

Arguments

Options

Example Output

Examples

List

Usage

Options

Example Output

Examples

Update

Usage

Options

Example Output

Examples

Activate

Usage

Options

Example Output

Deactivate

Usage

Options

Example Output

Examples

Status

Usage

Options

Example Output

Describe

Usage

Options

Example Output

Quick Reference

videosdk.yaml Reference

Next Steps