Deploying to the Cloud

Use agentuity deploy from a registered project when you are ready to build, upload, and activate a cloud deployment.

Before You Deploy

Deploy expects a local project linked to Agentuity Cloud. A linked project has agentuity.json and an Agentuity SDK key available through .env or your environment.

If you already have a framework app, or you created one with --no-register, import it first:

agentuity project import --name my-app

Validate first when you are adding Agentuity to an app you already have:

agentuity project import --validate-only
agentuity project import --name my-app --confirm

For monorepos, import the app package:

agentuity project import --dir apps/web --name web --confirm

Then deploy:

agentuity deploy

The deploy command can reconcile missing project configuration interactively, but importing first gives you a clear setup step before the build starts.

Deploy Your Project

Deploy the current project:

agentuity deploy

If your package.json has a deploy script, this is also valid:

npm run deploy

The deploy flow:

1. Checks project registration and region.
2. Syncs non-Agentuity values from local env files (default .env, or files passed with --env).
3. Creates a deployment record.
4. Builds, verifies, and packages the deployment bundle.
5. Sends launch metadata and static asset metadata to Agentuity Cloud.
6. Encrypts and uploads the deployment bundle.
7. Uploads static assets when the build emitted them.
8. Provisions and activates the deployment.

Multiple Environments

Use the same codebase against different Agentuity projects (staging, production, and so on) with two flags:

# Staging
agentuity deploy \
  --project-config agentuity.staging.json \
  --env .env \
  --env .env.staging
 
# Production
agentuity deploy \
  --project-config agentuity.production.json \
  --env .env \
  --env .env.production

Typical layout:

agentuity.json                 # local default (optional)
agentuity.staging.json         # staging projectId, domains, resources
agentuity.production.json      # production projectId, domains, resources
.env                           # shared base values
.env.staging                   # staging overrides (including AGENTUITY_SDK_KEY)
.env.production                # production overrides

Each config file is a full agentuity.json shape: different projectId, orgId, region, and deployment.domains as needed. Register each environment once (for example by importing against a copy of the config, or creating separate cloud projects and saving the resulting metadata under the staging/production filenames).

--env is global, so it works with other commands too:

agentuity --env .env --env .env.staging cloud env push
agentuity --env .env.staging dev

You can also pass comma-separated paths: --env .env,.env.staging.

Profile-based alternatives still work: an active CLI profile named staging prefers agentuity.staging.json and .env.staging when those files exist. Prefer --project-config and --env when you want an explicit path without switching profiles. See CLI Profiles.

Example output:

✓ Sync Env & Secrets
✓ 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/r/deploy_abc123xyz

Deployment Bundle

During deploy, the CLI runs the same framework detection and adapter pipeline used by agentuity build. The result is a .agentuity deployment bundle with:

For non-Agentuity framework apps, deploy metadata contains empty Agentuity route and agent lists, plus the launch metadata and any static assets discovered in the framework build output.

Monorepo Staging and .agentuityignore

When the app is a workspace subpackage (for example apps/web under a root with workspaces or pnpm-workspace.yaml), the CLI stages the monorepo root into .agentuity/ so runtime install can resolve workspace:* dependencies. That mirror can include sibling apps, docs, and local tooling you do not want in the upload.

File locations

Both files use gitignore syntax. Patterns from both are combined; later patterns can override earlier ones the same way nested .gitignore files do.

Pattern roots

All patterns are matched against paths relative to the monorepo root — the tree that gets staged — even when the ignore file lives in a subpackage.

# These refer to monorepo-root paths, not apps/web/...
experiments/
scripts/
apps/desktop/
docs/

So experiments/ excludes <monorepo-root>/experiments/, not only apps/web/experiments/.

Built-in exclusions

These always apply and cannot be re-included with ! negation:

Example

# Sibling apps not needed to run this package
apps/desktop/
apps/debug-cli/
 
# Research, docs, CI, local tooling
.agents/
experiments/
scripts/
docs/
dist/
reports/
tests/
tools/
security/
.github/
 
# Caches and native build trees
**/target/
**/.turbo/
**/.next/
**/.vite/
**/coverage/
 
# Non-runtime prose
**/*.md
**/*.mdx

Do not exclude workspace packages your app imports via workspace:* (for example packages/shared). Prefer excluding sibling apps and non-runtime trees.

Protected paths

Bare patterns like dist/ match any directory named dist (gitignore rules). That would also match the target package’s build output (apps/web/dist). The CLI keeps these required paths even when they match a user pattern, and logs a warning:

Built-in safety rules still apply under the package (node_modules, .env*, …). Prefer scoped excludes for other packages’ output, for example docs/dist/ or apps/other/dist/, instead of bare dist/.

Staging behavior

• Each monorepo pack/deploy wipes the staging directory before copying, so newly ignored paths do not linger from a previous run.
• Excluding a directory counts as one skip at that path; nested files never enter staging.
• Ignore exclusions apply during staging, before the deploy zip is built. Zip-step "skipped" counts only refer to filter/symlink handling inside the already-staged tree.

See also Building Deployment Bundles and the how-to in Deploy Framework Apps.

Inspect the Package Without Uploading

Use pack-only mode to build and zip the same staging tree deploy would upload, without creating a cloud deployment or encrypting the upload:

agentuity deploy --pack-only
agentuity deploy --pack-only --log-level=trace
agentuity deploy --pack-only --pack-output ./out/deploy.zip

Default output is agentuity-deploy.zip next to the project (the app package when you pass --dir apps/web). List contents with:

unzip -l agentuity-deploy.zip

With --log-level=trace (or --log-level trace), the CLI prints every path excluded during monorepo staging and every file added to the zip. Build logs also summarize how many paths .agentuityignore excluded.

Pack-only still expects a registered project (agentuity.json) for the same project context as deploy. It does not create a deployment record or upload artifacts.

Deploy Options

Global CLI options can be placed before the command:

agentuity --log-level debug deploy
agentuity --log-level=trace deploy --pack-only
agentuity --dry-run deploy
agentuity --json deploy
agentuity --env .env --env .env.staging deploy --project-config agentuity.staging.json

Deployment URLs

A successful deploy can return a deployment URL, a project URL, and configured custom domains.

The project URL points to the active deployment and updates after each successful deploy.

Viewing Deployments

List recent deployments:

agentuity cloud deployment list
agentuity cloud deployment list --count=25
agentuity cloud deployment list --project-id=proj_abc123xyz

Show one deployment:

agentuity cloud deployment show deploy_abc123xyz
agentuity cloud deployment show deploy_abc123xyz --project-id=proj_abc123xyz

View deployment logs:

agentuity cloud deployment logs deploy_abc123xyz
agentuity cloud deployment logs deploy_abc123xyz --limit=50
agentuity cloud deployment logs deploy_abc123xyz --no-timestamps
agentuity cloud deployment logs deploy_abc123xyz --project-id=proj_abc123xyz

Rollback, Undeploy, and Delete

Roll back to the previous completed deployment:

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

Stop the active deployment:

agentuity cloud deployment undeploy
agentuity cloud deployment undeploy --force
agentuity cloud deployment undeploy --project-id=proj_abc123xyz

Delete one deployment:

agentuity cloud deployment delete deploy_abc123xyz
agentuity cloud deployment delete deploy_abc123xyz --force
agentuity cloud deployment delete deploy_abc123xyz --project-id=proj_abc123xyz

Environment Variables

Deploy syncs values from local env files before the build step. By default it reads .env. Pass global --env one or more times to load a different set of files (merged in order; later keys win):

agentuity deploy --env .env --env .env.staging

Keys that start with AGENTUITY_ are filtered out of the cloud sync because the platform manages them. AGENTUITY_SDK_KEY is still required locally for the deploy client; it is loaded from process.env after --env files are applied, or from the usual profile file search.

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

Variables with secret-looking suffixes such as _SECRET, _KEY, _TOKEN, _PASSWORD, or _PRIVATE are stored as secrets. Other values are stored as regular environment variables.

See Managing Environment Variables for layered --env details.

Regions

Set a default region:

agentuity cloud region select usw

Show or clear it:

agentuity cloud region current
agentuity cloud region unselect

The selected project region is stored in agentuity.json:

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

If the local region differs from the server region, interactive deploys prompt before updating it. In non-interactive runs, pass --confirm when you intend to accept the region change.

Custom Domains

Add custom domains in agentuity.json:

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

Deploy validates DNS before activating the domains. The required CNAME value is shown by the CLI and in deployment details.

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

Runtime and Build Resources

Configure runtime resources in agentuity.json:

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

Configure build resources separately when framework compilation needs more capacity:

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

Runtime resources affect the deployed app. Build resources affect the build sandbox used to compile and package it.

Machines

Machines are the compute instances running deployments. Use these commands when you need to inspect or manage them:

agentuity cloud machine list
agentuity cloud machine get machine_abc123xyz
agentuity cloud machine deployments machine_abc123xyz
agentuity cloud machine delete machine_abc123xyz

Deploy Lifecycle Scripts

npm run deploy follows normal package manager lifecycle hooks. Add predeploy and postdeploy scripts when you want local work to run before or after the CLI command.

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

predeploy and postdeploy run when you call npm run deploy. They do not run when you call agentuity deploy directly.

CI Deployments

CI systems can pass git and pull request metadata directly to agentuity deploy:

agentuity deploy \
  --trigger workflow \
  --event pull_request \
  --branch "$GITHUB_HEAD_REF" \
  --commit "$GITHUB_SHA" \
  --repo "$GITHUB_REPOSITORY" \
  --provider github

When a CI system pre-creates the deployment, it can pass AGENTUITY_DEPLOYMENT:

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

The JSON object requires id, orgId, and publicKey.

Next Steps

• Build Configuration: Inspect the local deployment bundle before deploy
• Debugging Deployments: Connect with SSH and inspect deployed behavior
• App Configuration: Configure project metadata and environment files