Agentuity Docs

Deploy your agents to Agentuity Cloud with automatic infrastructure provisioning.

Deploy your Agentuity project to the cloud with a single command. The platform handles infrastructure, scaling, and monitoring automatically.

Deploy Your Project

agentuity deploy
# or
bun run deploy

The deploy command:

Syncs environment variables from .env.production (or .env as fallback)
Builds and packages your project
Encrypts and uploads the deployment bundle securely
Provisions your deployment on Agentuity's infrastructure
Activates your deployment

View in Console

After deployment, view your environment variables and secrets in the Agentuity Console under Project > Settings.

Example output:

✓ Sync Env & Secrets
✓ Create Deployment
✓ Build, Verify and Package
✓ Encrypt and Upload Deployment
✓ Provision Deployment

Your project was deployed!

→ Deployment ID:  dep_abc123xyz
→ Deployment URL: https://dep-abc123xyz.agentuity.cloud
→ Project URL:    https://proj-456def.agentuity.cloud
→ Dashboard:      https://app-v1.agentuity.com/deployments/dep_abc123xyz

The Dashboard URL links directly to the deployment details in the Agentuity Console.

Deployment URLs

Each deployment gets two URLs:

Deployment URL (dep_xxx.agentuity.cloud):

Unique URL for this specific deployment
Persists even after new deployments
Use for testing a specific version

Project URL (proj_xxx.agentuity.cloud):

Always points to the active deployment
Updates automatically when you deploy
Use for stable endpoints and webhooks

# Deploy creates both URLs
agentuity deploy
 
# Deployment URL: https://dep-abc123.agentuity.cloud
# Project URL:    https://proj-456def.agentuity.cloud

URL Structure

Both URLs are automatically provisioned and support HTTPS. The project URL automatically routes to the active deployment.

Tagging Deployments

Add tags to label deployments:

# Single tag
agentuity deploy --tag staging
 
# Multiple tags
agentuity deploy --tag staging --tag hotfix-123

Tags appear in deployment lists and help organize versions:

agentuity cloud deployment list
# Shows tags column for each deployment

Viewing Deployments

List recent deployments:

# Show 10 most recent
agentuity cloud deployment list
 
# Custom count
agentuity cloud deployment list --count=25
 
# For a specific project
agentuity cloud deployment list --project-id=proj_abc123xyz

Example output:

ID	State	Active	Created	Tags
dep_abc123	completed	Yes	12/1/25, 3:45 PM	staging
dep_def456	completed		12/1/25, 2:30 PM	v1.2.0
dep_ghi789	completed		11/30/25, 5:00 PM

Deployment Details

View detailed information about a deployment:

# Show deployment details
agentuity cloud deployment show dep_abc123xyz
 
# For specific project
agentuity cloud deployment show dep_abc123xyz --project-id=proj_abc123

Output includes:

Deployment ID, state, and creation time
Active status
Tags and custom domains
Cloud region
Git metadata (repo, commit, branch, PR)
Build information (SDK version, runtime, platform)

ID:       dep_abc123xyz
Project:  proj_456def
State:    completed
Active:   Yes
Created:  12/1/25, 3:45 PM
Tags:     staging, hotfix-123

Git Information
  Repo:     myorg/myapp
  Branch:   main
  Commit:   a1b2c3d
  Message:  Fix authentication bug

Build Information
  Agentuity: 1.0.0
  Bun:       1.1.40
  Platform:  linux
  Arch:      x64

Viewing Logs

Fetch logs for a deployment:

# View logs
agentuity cloud deployment logs dep_abc123xyz
 
# Limit log entries
agentuity cloud deployment logs dep_abc123xyz --limit=50
 
# Hide timestamps
agentuity cloud deployment logs dep_abc123xyz --no-timestamps
 
# For specific project
agentuity cloud deployment logs dep_abc123xyz --project-id=proj_abc123

Logs show severity (INFO, WARN, ERROR) and message body with color-coded output.

Real-Time Logs

For live streaming logs, use SSH access. See Debugging for SSH setup.

Rolling Back

Revert to a previous deployment:

agentuity cloud deployment rollback

The command:

Finds the previous completed deployment
Prompts for confirmation
Activates the previous deployment
Updates the project URL

Rollback to deployment dep_def456? (y/N): y
✓ Rolled back to deployment dep_def456

Use for specific projects:

agentuity cloud deployment rollback --project-id=proj_abc123xyz

Rollback Behavior

Rollback activates the most recent completed deployment before the current one. The current deployment remains available at its deployment URL but is no longer active.

Undeploying

Stop the active deployment:

# With confirmation prompt
agentuity cloud deployment undeploy
 
# Skip confirmation
agentuity cloud deployment undeploy --force
 
# For specific project
agentuity cloud deployment undeploy --project-id=proj_abc123xyz

After undeploying:

The project URL becomes unavailable
All deployment-specific URLs remain accessible
Previous deployments are not deleted
You can redeploy or rollback at any time

Undeploy Impact

Undeploying stops the active deployment immediately. Your project URL will return 404 until you deploy or rollback.

Removing Deployments

Permanently delete a deployment:

# Remove a specific deployment
agentuity cloud deployment remove dep_abc123xyz
 
# For specific project
agentuity cloud deployment remove dep_abc123xyz --project-id=proj_abc123xyz

Permanent Deletion

Removing a deployment permanently deletes it. You cannot rollback to a removed deployment.

Custom Domains

You can configure custom domains using either the configuration file or CLI commands.

Option 1: Configuration File

Configure custom domains in agentuity.json:

{
  "projectId": "proj_abc123xyz",
  "orgId": "org_def456",
  "region": "us-east-1",
  "deployment": {
    "domains": ["api.example.com", "app.example.com"]
  }
}

Available Regions

Available regions are fetched from the API at deployment time. If multiple regions are available, the CLI prompts you to select one.

DNS Configuration

Add a CNAME record for each custom domain. A CNAME record tells DNS to resolve your domain to Agentuity's servers:

Type:  CNAME
Name:  api.example.com
Value: p<hash>.agentuity.cloud
TTL:   600

The p<hash> value is your project's unique identifier, shown when you run agentuity deploy or in the Console.

The CLI validates DNS records during deployment:

agentuity deploy

✓ Validate Custom Domains: api.example.com, app.example.com
✓ Sync Env & Secrets
...

DNS Validation

Deployment fails if DNS records are missing or incorrect. The CLI shows the required CNAME value in the error message.

Multiple Domains

Custom domains replace the default URLs:

{
  "deployment": {
    "domains": ["api.example.com"]
  }
}

After deployment with custom domains, the CLI only shows custom URLs:

→ Deployment ID:  dep_abc123xyz
→ Deployment URL: https://api.example.com

The project URL and deployment-specific URLs still exist but custom domains take precedence in the output.

Option 2: CLI Commands

Manage custom domains directly from the CLI:

# List configured domains
agentuity cloud domain list
 
# Add a domain
agentuity cloud domain add api.example.com
 
# Remove a domain
agentuity cloud domain remove api.example.com
 
# Verify DNS configuration
agentuity cloud domain verify api.example.com

When to Use Each Approach

Use the configuration file for domains that should persist across deployments. Use CLI commands for quick testing or temporary domains.

If you're using the AI Gateway, you don't need to include provider API keys (like OPENAI_API_KEY). The gateway handles authentication automatically. Only include provider keys if you're bypassing the gateway.

Variables are automatically:

Filtered (removes AGENTUITY_ prefixed keys)
Categorized (regular env vs secrets based on naming)
Encrypted (secrets only)
Synced to cloud before the build step

Secrets Detection

Variables with suffixes like _SECRET, _KEY, _TOKEN, _PASSWORD, or _PRIVATE are automatically encrypted as secrets. All other variables are stored as regular environment variables.

Deploy Options

Option	Description
`--tag <name>`	Add deployment tag (repeatable)
`-f, --force`	Force deployment without confirmation
`--dry-run`	Simulate deployment without executing
`--log-level debug`	Show verbose output
`--project-id <id>`	Deploy specific project

# Verbose deployment
agentuity deploy --log-level=debug
 
# Multiple tags
agentuity deploy --tag staging --tag v1.2.0
 
# Specific project
agentuity deploy --project-id=proj_abc123xyz
 
# Simulate deployment
agentuity deploy --dry-run
 
# Force deployment
agentuity deploy --force

Next Steps

Debugging Deployments: SSH access and debugging tools
Logging: Configure logging in your agents
Key-Value Storage: Store persistent data

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Deploying to the Cloud