Deploying Agents - TerminalUse

Quick Start

Already have an agent? Deploy it in seconds:

# 1. Make sure you're logged in
tu auth login

# 2. Deploy (from your agent directory)
tu deploy

That’s it. The CLI handles building, pushing, and deploying.

The Config

Your config file (config.yaml) is the single source of truth for deployment. It tells the CLI where your code is, how to build it, and how to deploy it.

agent:
  name: my-namespace/my-agent   # Must be in namespace/agent-name
  description: My first agent   
  sdk_type: claude_agent_sdk    
  temporal:
    enabled: false              

Build Configuration

build:
  context:
    root: ./                    # Root directory for Docker build
    include_paths: .            # Paths to include in build context
    dockerfile: Dockerfile      # Path to Dockerfile (relative to root)
    dockerignore: .dockerignore # Optional: path to .dockerignore

Deployment Configuration

deployment:
  production:
    replicaCount: 1
    resources:
      requests:
        cpu: "500m"
        memory: "6Gi"
      limits:
        cpu: "1000m"
        memory: "6Gi"
    areTasksSticky: true        # Tasks stay on old version during deploy

  preview:
    replicaCount: 1
    resources:
      requests:
        cpu: "250m"
        memory: "2Gi"
      limits:
        cpu: "500m"
        memory: "2Gi"
    areTasksSticky: false       # Tasks migrate to new version immediately

Environments & Branches

When you create an agent, two environments are created for it by default:

Environment	Git Branch	Default Behavior
Production	`main`	Higher resources, tasks stay on old version when a new version is deployed. Must explicitly migrate tasks to new versions
Preview	all other branches	Lower resources, tasks migrate to new versions immediately

Additional environments (like staging) can also be created.

Task Stickiness

When you deploy a new version, what happens to running tasks?

Setting	Behavior
`areTasksSticky: true` (production default)	Running tasks stay on old version until complete
`areTasksSticky: false` (preview default)	Running tasks migrate to new version immediately

In production, if your new version doesn’t have a breaking change, you’ll want to migrate your tasks to your latest version. You can do this with tu tasks migrate --from <version_id> --to latest.

Environment Resolution

Environments are determinted automatically based on the current git branch you’re on:

CLI detects your current git branch
Platform API resolves branch → environment
CLI uses the matching config (deployment.production or deployment.preview)

# On main branch → uses deployment.production
git checkout main
tu deploy

# On feature branch → uses deployment.preview
git checkout feature/new-thing
tu deploy

Managing Environment Variables

# List all environment variables
tu env ls

# Add a variable (interactive prompts for value and environment)
tu env add DATABASE_URL

# Mark env var as secret (cannot be retrieved later)
tu env add API_KEY -v "sk-xxx" -e prod --secret

# Remove a variable
tu env rm API_KEY --environment all

Bulk Import from .env File

Import multiple variables at once from a .env file:

# Import to .env to all environments
tu env import .env -e all

# Mark specific keys as secrets
tu env import .env -e prod --secret API_KEY --secret DB_PASSWORD

Pull Variables to Local File

Download your remote environment variables to a local .env file for local development:

# Pull from preview to .env.local (default)
tu env pull

# Pull from production
tu env pull .env.production -e prod

Secrets cannot be retrieved and are included as empty placeholders in pulled files.

Environment variables are injected at runtime and accessible via standard methods:

import os

# Access environment variables
api_key = os.environ.get("API_KEY")
database_url = os.environ["DATABASE_URL"]

Resource Sizing Guide

Recommendations based on agent complexity:

Agent Type	CPU Request	Memory Request	Notes
Minimum	`500m`	`2Gi`	Claude Agent SDK takes up `1.1Gi`
Minimum for Prodcution	`500`	`6Gi`	Additional room to process concurent tasks on one replica

CPU units: 1 = 1 full core, 500m = 0.5 cores. Memory units: 1Gi = 1 gibibyte.

Replicas scale up as memory or CPU limits are reached. We recommend having a minimum of 6Gi on one replica in production to handle multiple concurrent requests as more replicas scale up.

Rollback

If something goes wrong with a deployment, you can rollback to the previous version:

tu rollback

This shows recent versions and prompts you to confirm:

Version ID	Git Hash	Status	Deployed
e77b7dc1	f8c3a91	current	3 mins ago
c2bad41e	27da232	retired	1 hour ago

Rollback summary:
  From: e77b7dc1 → To: c2bad41e
  Git:  f8c3a91 → 27da232

Note: Pending secrets will NOT be modified.
      The rollback uses the secrets snapshot from the target version.

? Rollback 'production' to version c2bad41e? Yes

✓ Rollback initiated for 'production'
  From: e77b7dc1 (f8c3a91)
  To:   c2bad41e (27da232)

Rollbacks use the secrets snapshot from the target version. Pending secret changes are not applied.

Deployment History

Use tu ls to see all deployments for your agent:

tu ls

Age	Branch	Version	Status	Git
40 mins ago	preview/feature-branch	b9044640	active	f8c3a91
43 mins ago	preview/feature-branch	ae4ce86f	retired	27da232

Deployment States

State	Meaning
`active`	Deployment succeeded, agent is running
`failed`	Deployment failed (check logs)
`timeout`	Deployment took too long
`unhealthy`	Agent deployed but health checks failing
`retired`	Old version being phased out

Events

Events provide a more granular view into the deployment history for a branch, showing each state transition as it happens.

tu ls preview/feature-branch

Age	Event	Version	Git	Trigger
41 mins ago	RETIRED	ae4ce86f	27da232	cleanup
41 mins ago	TASKS_MIGRATED	b9044640	f8c3a91	deploy
41 mins ago	ACTIVATED	b9044640	f8c3a91	container_register
41 mins ago	CREATED	b9044640	f8c3a91	deploy

Event Types

Event	Meaning
`CREATED`	Version was created and deployment started
`ACTIVATED`	Version is now active and receiving traffic
`FAILED`	Deployment failed
`DRAINING`	Version is draining (tasks being migrated away)
`RETIRED`	Version has been retired and is no longer active
`ROLLED_BACK_FROM`	This version was rolled back from
`ROLLED_BACK_TO`	This version was rolled back to
`REDEPLOYED`	Version was redeployed (when secrets are updated)
`TASKS_MIGRATED`	Tasks were migrated to this version
`CLEANUP_FAILED`	Cleanup of this version failed

CLI Commands

`tu deploy`

tu deploy [OPTIONS]

Option	Short	Default	Description
`--config`	`-c`	`config.yaml`	Path to manifest file
`--branch`		auto-detected	Override git branch
`--yes`	`-y`	`false`	Skip confirmation prompts
`--verbose`	`-v`	`false`	Show Docker build output

`tu rollback`

tu rollback [OPTIONS]

Option	Short	Default	Description
`--env`	`-e`	auto-detected	Environment to rollback
`--version`	`-v`	previous	Target version ID to rollback to
`--yes`	`-y`	`false`	Skip confirmation prompts
`--config`	`-c`	`config.yaml`	Path to config file

`tu ls`

tu ls [BRANCH] [OPTIONS]

Option	Short	Default	Description
`BRANCH`			Branch name to show events for (optional)
`--limit`	`-n`	`10`	Number of items to show
`--all`		`false`	Include retired branches
`--config`	`-c`	`config.yaml`	Path to config file

Without a branch argument, shows recent versions across all branches. With a branch name, shows lifecycle events for that branch.

Build with Terminal Use

​Quick Start

​The Config

​Environments & Branches

​Task Stickiness

​Environment Resolution

​Managing Environment Variables

​Bulk Import from .env File

​Pull Variables to Local File

​Resource Sizing Guide

​Rollback

​Deployment History

​Deployment States

​Events

​Event Types

​CLI Commands

​tu deploy

​tu rollback

​tu ls

Quick Start

The Config

Environments & Branches

Task Stickiness

Environment Resolution

Managing Environment Variables

Bulk Import from .env File

Pull Variables to Local File

Resource Sizing Guide

Rollback

Deployment History

Deployment States

Events

Event Types

CLI Commands

`tu deploy`

`tu rollback`

`tu ls`