# Deploying to the Cloud

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.

## 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

```bash
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](https://app.agentuity.com) 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.agentuity.com/deployments/dep_abc123xyz
```

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

## 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

```bash
# Deploy creates both URLs
agentuity deploy

# Deployment URL: https://dep-abc123.agentuity.cloud
# Project URL:    https://proj-456def.agentuity.cloud
```

Both URLs are automatically provisioned with HTTPS. The project URL always routes to the active deployment.

## Viewing Deployments

List recent deployments:

```bash
# 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 | Message | 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:

```bash
# 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
- DNS records (for custom domain configuration)
- 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
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
```

> [!TIP]
> **DNS Records**
> When custom domains are configured, the `show` command displays the required DNS records for each domain. Use this to verify your CNAME configuration.

## Viewing Logs

Fetch logs for a deployment:

```bash
# 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.

> [!NOTE]
> **Real-Time Logs**
> For live streaming logs, use SSH access. See [Debugging](/reference/cli/debugging) for SSH setup.

## Rolling Back

Revert to a previous deployment:

```bash
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 dep_def456? (y/N): y
✓ Rolled back to deployment dep_def456
```

Use for specific projects:

```bash
agentuity cloud deployment rollback --project-id=proj_abc123xyz
```

> [!WARNING]
> **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:

```bash
# 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

> [!WARNING]
> **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:

```bash
# Remove a specific deployment
agentuity cloud deployment remove dep_abc123xyz

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

> [!WARNING]
> **Permanent Deletion**
> Removing a deployment permanently deletes it. You cannot rollback to a removed deployment.

## Preview Environments

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

```bash
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.

> [!WARNING]
> **GitHub Connection Required**
> Preview environments require a connected GitHub repository. See [Agentuity GitHub App](/reference/github-app) for how automated deployments work, or [Setting Up Git Integration](/reference/cli/git-integration) for CLI setup.

## 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:

```bash
# 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:

```json
{
  "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`:

```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:

```bash
agentuity deploy
```

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

> [!WARNING]
> **DNS Validation**
> Deployment fails if DNS records are missing or incorrect. The CLI shows the required CNAME value in the error message.

> [!NOTE]
> **Activate Custom Domains**
> After adding a custom domain to your configuration, you must deploy to activate it. The domain becomes active only after a successful deployment.

### Multiple Domains

Custom domains replace the default URLs:

```json
{
  "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.

## Resource Configuration

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

```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](#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.

```json
{
  "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:**

| Field | Description | Example |
|-------|-------------|---------|
| `timeout` | Maximum time allowed for the build step | `"30m"` |
| `resources.memory` | Memory available in the build sandbox | `"4Gi"` |
| `resources.cpu` | CPU cores available in the build sandbox | `"2"` |
| `resources.disk` | Disk space available in the build sandbox | `"4Gi"` |

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

> [!TIP]
> **When to Override Build Resources**
> If your build frequently times out or runs out of memory, increase `build.resources.memory` or `build.timeout` before adjusting runtime `deployment.resources`. Build and runtime environments are separate.

## Environment Variables

The deploy command syncs variables from your `.env` file.

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

> [!NOTE]
> **AI Provider Keys**
> If you're using the [AI Gateway](/agents/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

> [!NOTE]
> **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.

## 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:

```bash
# List all machines for current project
agentuity cloud machine list

# Get details for a specific machine
agentuity cloud machine get mach_abc123xyz

# Delete a machine
agentuity cloud machine delete mach_abc123xyz

# List deployments running on a machine
agentuity cloud machine deployments mach_abc123xyz
```

Machine details include status, region, resource allocation, and uptime. Use machine management to:
- Monitor infrastructure health
- Debug performance issues
- Clean up unused machines

> [!WARNING]
> **Deleting Machines**
> Deleting a machine immediately terminates any deployments running on it. Only delete machines that are unused or when intentionally removing capacity.

## Deploy Options

| Option | Description |
|--------|-------------|
| `-y, --confirm` | Skip all confirmation prompts (useful for CI/CD) |
| `--dry-run` | Simulate deployment without executing (place before `deploy`) |
| `--log-level debug` | Show verbose output |
| `--project-id <id>` | Deploy specific project |
| `--message <msg>` | Message to associate with this build |

```bash
# 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.

```json title="package.json"
{
  "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

> [!WARNING]
> **Local vs GitHub App Behavior**
> When you run `bun run deploy` locally, `predeploy` and `postdeploy` are standard npm lifecycle hooks. They do **not** run when calling `agentuity deploy` directly.
>
> When deploying via the [Agentuity GitHub App](/reference/github-app#build-process), `predeploy` has additional meaning: if defined, it runs **instead of** the platform's automatic `bun install`. If you don't define `predeploy`, the platform installs dependencies for you. See [Build Process](/reference/github-app#build-process) for details.

## 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:

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

The JSON object requires:

| Field | Description |
|-------|-------------|
| `id` | The deployment ID |
| `orgId` | Your organization ID |
| `publicKey` | The deployment's public key |

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

> [!NOTE]
> **Getting Deployment Details**
> Pre-created deployments are typically provisioned by external systems like GitHub Actions workflows or custom CI pipelines that integrate with the Agentuity API.

## Next Steps

- [Debugging Deployments](/reference/cli/debugging): SSH access and debugging tools
- [Logging](/services/observability/logging): Configure logging in your agents
- [Key-Value Storage](/services/storage/key-value): Store persistent data