Deploying to the Cloud

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

Why Deploy to Agentuity?

Deploying agents should be as easy as deploying a web app. But agents need long-running processes, persistent storage, sandbox environments, and observability built in. Setting this up yourself means stitching together containers, databases, secret management, and monitoring.

Agentuity handles all of this automatically. You push code, and the platform provisions everything your agents need: compute, storage, networking, and observability. No infrastructure configuration, no Docker files, no Kubernetes.

What this gives you:

• Single-command deployment: agentuity deploy handles build, upload, and provisioning
• Automatic HTTPS: Every deployment gets secure URLs with SSL certificates
• Built-in rollback: Revert to any previous deployment instantly
• Zero infrastructure management: No containers, orchestration, or scaling to configure

Deploy Your Project

agentuity deploy
# or
bun run deploy

The deploy command:

1. Syncs environment variables from .env
2. Builds and packages your project
3. Encrypts and uploads the deployment bundle securely
4. Provisions your deployment on Agentuity's infrastructure
5. Activates your deployment

After deployment, view your environment variables and secrets in the Web App 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:  deploy_abc123xyz
→ Deployment:     https://<deployment-url>
→ Project:        https://<project-url>
→ Dashboard:      https://app.agentuity.com/projects/proj_456def/deployments/deploy_abc123xyz

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

Deployment URLs

Each deployment gets two URLs:

Deployment URL:

• 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://<deployment-url>
# Project URL:    https://<project-url>

Both URLs are automatically provisioned with HTTPS. The project URL always routes to the active 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:

Deployment Details

View detailed information about a deployment:

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

Output includes:

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

ID:          deploy_abc123xyz
Project:     proj_456def
State:       completed
Active:      Yes
Created:     12/1/25, 3:45 PM
Tags:        staging, hotfix-123
Domains:     api.example.com
DNS Records: api.example.com CNAME p1234567890.agentuity.run

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 deploy_abc123xyz
 
# Limit log entries
agentuity cloud deployment logs deploy_abc123xyz --limit=50
 
# Hide timestamps
agentuity cloud deployment logs deploy_abc123xyz --no-timestamps
 
# For specific project
agentuity cloud deployment logs deploy_abc123xyz --project-id=proj_abc123

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

Rolling Back

Revert to a previous deployment:

agentuity cloud deployment rollback

The command:

1. Finds the previous completed deployment
2. Prompts for confirmation
3. Activates the previous deployment
4. Updates the project URL

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

Use for specific projects:

agentuity cloud deployment rollback --project-id=proj_abc123xyz

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

Deleting Deployments

Permanently delete a deployment:

# Delete a specific deployment
agentuity cloud deployment delete deploy_abc123xyz
 
# For specific project
agentuity cloud deployment delete deploy_abc123xyz --project-id=proj_abc123xyz
 
# Skip confirmation
agentuity cloud deployment delete deploy_abc123xyz --force

Preview Environments

Deploy pull requests to isolated preview environments for testing before merging. Enable previews when linking your repository:

agentuity git link --preview true

Or toggle it in the Web App under your project's Settings > GitHub > Preview Environments.

Once enabled, every pull request to your connected repository automatically deploys to a unique preview URL. This allows you to:

• Test changes in an isolated environment before merging
• Share preview links with reviewers
• Run integration tests against the preview deployment

Preview environments are automatically cleaned up when the pull request is closed or merged.

Regions

Agentuity Cloud deploys to multiple geographic regions. Choose a region based on latency requirements and data residency needs.

Available Regions

• use - US East
• usc - US Central
• usw - US West

More regions coming soon.

Setting a Default Region

Set a default region to skip the selection prompt on every deployment:

# Set default region
agentuity cloud region select usw
 
# View current default
agentuity cloud region current
 
# Clear default (prompts on each deploy)
agentuity cloud region unselect

Region in Configuration

The region is stored in agentuity.json after your first deployment:

{
  "projectId": "proj_abc123xyz",
  "orgId": "org_def456",
  "region": "use"
}

Changing Regions

When you deploy to a different region than the one in agentuity.json, the CLI prompts for confirmation. This prevents accidental region changes that could affect latency or data residency.

Cross-Region Resources

The SDK automatically handles cross-region resource access. If you create a sandbox or storage resource in one region and access it from another, the platform routes requests transparently. No configuration needed.

Custom Domains

Configure custom domains in agentuity.json:

{
  "projectId": "proj_abc123xyz",
  "orgId": "org_def456",
  "region": "use",
  "deployment": {
    "domains": ["api.example.com", "app.example.com"]
  }
}

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.run
TTL:   600

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

The CLI validates DNS records during deployment:

agentuity deploy

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

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:  deploy_abc123xyz
→ Deployment URL: https://api.example.com

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

Resource Configuration

Configure CPU, memory, and disk limits in agentuity.json:

{
  "deployment": {
    "resources": {
      "cpu": "500m",
      "memory": "500Mi",
      "disk": "500Mi"
    },
    "domains": []
  }
}

Defaults: cpu: "500m", memory: "500Mi", disk: "500Mi". Increase as needed for your workload.

The domains array is empty by default. Add custom domains when needed (see Custom Domains).

Configuring Build Resources

deployment.resources controls how much CPU, memory, and disk your agent gets at runtime. build controls the sandbox resources available during the build step, when your project is compiled and bundled.

{
  "deployment": {
    "resources": {
      "cpu": "500m",
      "memory": "500Mi",
      "disk": "500Mi"
    }
  },
  "build": {
    "timeout": "30m",
    "resources": {
      "memory": "4Gi",
      "cpu": "2",
      "disk": "4Gi"
    }
  }
}

Build resource defaults are platform-managed. Override them when builds require more capacity: large dependency trees, heavy compilation steps, or complex bundling.

Build fields:

All fields are optional. Omit build entirely to use platform defaults.

Environment Variables

The deploy command syncs variables from your .env file.

# .env
DATABASE_URL=postgres://...
WEBHOOK_SECRET=secret123
MY_CUSTOM_API_KEY=xxx

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

Machine Management

Machines are the compute instances running your deployments. View and manage them when debugging infrastructure issues.

View and manage the machines running your deployments:

# List all machines for current project
agentuity cloud machine list
 
# Get details for a specific machine
agentuity cloud machine get machine_abc123xyz
 
# Delete a machine
agentuity cloud machine delete machine_abc123xyz
 
# List deployments running on a machine
agentuity cloud machine deployments machine_abc123xyz

Machine details include status, region, resource allocation, and uptime. Use machine management to:

• Monitor infrastructure health
• Debug performance issues
• Clean up unused machines

Deploy Options

# Verbose deployment
agentuity deploy --log-level=debug
 
# Specific project
agentuity deploy --project-id=proj_abc123xyz
 
# With a message
agentuity deploy --message "Fix authentication bug"
 
# Simulate deployment (dry run)
agentuity --dry-run deploy
 
# Skip confirmation prompts (for CI/CD)
agentuity deploy --confirm

Running Deploy Lifecycle Scripts

bun run deploy follows standard npm/bun lifecycle script conventions. Add predeploy and postdeploy scripts to package.json to run steps automatically before and after the deploy command.

{
  "scripts": {
    "predeploy": "bun run build:shared",
    "deploy": "agentuity deploy",
    "postdeploy": "echo 'Deploy complete'"
  }
}

predeploy runs before the deploy command and postdeploy runs after it completes.

Common use cases:

• predeploy: Install workspace dependencies, compile shared packages, run custom validation
• postdeploy: Send a notification, update a changelog, trigger downstream systems

CI/CD Pipelines

For automated deployments in CI/CD systems (GitHub Actions, GitLab CI, etc.), you can use a pre-created deployment.

Using Pre-Created Deployments

Set the AGENTUITY_DEPLOYMENT environment variable with deployment details:

export AGENTUITY_DEPLOYMENT='{"id":"deploy_xxx","orgId":"org_xxx","publicKey":"..."}'
agentuity deploy

The JSON object requires:

When this variable is set, the CLI:

• Skips deployment creation and uses the existing deployment
• Uses plain output mode (no TUI) for cleaner CI logs
• Validates the JSON schema before proceeding

Next Steps

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