Deploying Framework Apps

A framework deploy links the project once, then packages and uploads each build. agentuity deploy runs the framework build, writes the Agentuity launch metadata, uploads the bundle and static assets, and prints the URLs for the running deployment. Run agentuity build ahead of time when you want to inspect the output.

agentuity project import --validate-only
agentuity project import
agentuity build
agentuity deploy

These examples show agentuity ... for readability. If the CLI is project-local, run the same command through your package-manager exec wrapper, for example npx agentuity ..., bunx agentuity ..., pnpm exec agentuity ..., or yarn exec agentuity .... See Local versus global CLI for install and undo commands.

Register the Project

Validate the directory before doing anything that talks to the cloud:

agentuity project import --validate-only

The check requires a package.json with at least one of name, dependencies, or devDependencies, or an agentuity/ subdirectory with its own package.json. Nothing is written, nothing is created.

When the shape is right, register the project:

agentuity project import
agentuity project import --name "my-app"
agentuity project import --org-id <org-id>
agentuity project import --confirm

The first run creates a project record in your org, writes agentuity.json with projectId, orgId, and region, and adds AGENTUITY_SDK_KEY=... to .env. It also pushes any non-reserved values from .env into the cloud project so the deploy step has them available.

--confirm makes the command non-interactive: it accepts the default org, default region, and a name derived from the directory unless you pass --name. Use it in CI. Without --confirm and without a TTY, the import refuses to run.

In a monorepo, run import against the app package:

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

The project metadata and .env are written inside apps/web. A monorepo-aware build stages the deployment bundle from the workspace root and sets workingDirectory in launch.json for the app subdirectory.

Configure agentuity.json

agentuity project import writes the project link file with sensible defaults. Open it before your first deploy when you want to set the region, custom domains, or runtime limits.

{
  "$schema": "https://agentuity.dev/schema/cli/v1/agentuity.json",
  "projectId": "proj_...",
  "orgId": "org_...",
  "region": "use",
  "deployment": {
    "resources": { "memory": "500Mi", "cpu": "500m", "disk": "500Mi" },
    "domains": []
  },
  "build": {
    "timeout": "10m",
    "resources": { "memory": "4Gi", "cpu": "1000m", "disk": "20Gi" }
  }
}

Region

region is required. The CLI fetches the live region list from the API and caches it under ~/.config/agentuity/regions-<profile>.json, so a static region table is not part of these docs. List and select regions from the CLI:

agentuity cloud region list
agentuity cloud region select use
agentuity cloud region current

Deploy compares the local region with the server's record. If they diverge, an interactive deploy prompts before changing the project. In CI, pass --confirm to accept the change; without it, deploy refuses to update the region.

Runtime Resources

deployment.resources controls the running app's CPU, memory, and disk. Defaults apply when the field is omitted.

1000m, 0.5, and 1 mean one core, half a core, and one core respectively. There is no CLI flag to override these at deploy time. Edit agentuity.json and redeploy.

Build Resources

build.resources and build.timeout apply to the build environment when the GitHub App or another CI path runs your deploy. They are platform-defaulted when omitted. Bump them when builds time out or run out of memory under heavy framework dependencies.

Custom Domains

Domains live on deployment.domains as an array of strings. See Custom Domains for DNS records, validation behavior, and TLS provisioning.

Build and Inspect

agentuity deploy runs the build internally. Run it explicitly when you want to see the detector output, the bundled launch metadata, or the static assets that will be uploaded:

agentuity build
agentuity build --skip-type-check
agentuity build --outdir .agentuity-check
agentuity build --report-file build-report.json

The CLI walks a framework database, then falls back to a generic adapter that requires scripts.build, scripts.start, or main in package.json.

Detected framework definitions currently include:

Hono apps use the generic path, so they need explicit build and start scripts. See Hono Apps for the build-script setup.

After the build, .agentuity/ contains:

The bundle does not rely on your local node_modules/ directory. The deploy runtime installs dependencies from the copied manifest and lockfile before it starts the command in launch.json.

launch.json is the deploy gate's source of truth for what the platform will actually run. Read it before deploy if anything looks off:

{
  "processes": [
    { "type": "web", "command": "node server.js", "default": true }
  ],
  "framework": { "name": "nextjs" },
  "runtime": { "name": "node", "port": 3000 },
  "build": { "date": "2026-04-29T19:23:01.412Z", "duration": 8421 }
}

For a monorepo subpackage, expect a working directory:

{
  "processes": [
    {
      "type": "web",
      "command": "node server.js",
      "default": true,
      "workingDirectory": "apps/web"
    }
  ],
  "framework": { "name": "nextjs" },
  "runtime": { "name": "node", "port": 3000 }
}

The typecheck step runs bunx tsc --noEmit --skipLibCheck. --skip-type-check and --dev skip it; both are useful for fast packaging checks. Use a normal agentuity build before deploy when you want the same verification deploy uses.

Deploy

agentuity deploy
agentuity deploy --message "ship refresh-token endpoint"

agentuity deploy requires:

• An authenticated CLI session (agentuity auth login if not).
• A registered project (agentuity.json present).
• AGENTUITY_SDK_KEY available in .env (or in .env.<profile> when not on the local profile). If missing, deploy exits before building and points you to agentuity cloud env pull.

What runs, in order:

1. Reconcile the project. Confirms agentuity.json matches a real cloud project. In a TTY with no agentuity.json, the CLI offers to import; otherwise it fails with PROJECT_NOT_FOUND.
2. Region check. Compares the local agentuity.json region with the server. Prompts if they diverge or accepts --confirm in non-TTY mode.
3. SDK key check. Reads AGENTUITY_SDK_KEY from the profile-aware env files.
4. Create the deployment record. The server returns a deployment ID, an encryption public key, and a stream URL for warmup logs.
5. Validate custom domains (only when agentuity.json lists them; see Custom Domains).
6. Sync env and secrets. Reads .env, drops AGENTUITY_* reserved keys, splits into env vars and secrets, and pushes to the cloud project. This step is best effort: a failure is reported as skipped, not fatal.
7. Build, verify, and package. Runs typecheck, framework detection, the framework adapter's build, then writes launch.json. Uploads the build metadata to receive signed upload URLs.
8. Security scan. Compares the project's node_modules against a malware blocklist that started running in parallel with the build. A block verdict halts the deploy.
9. Encrypt and upload. Zips .agentuity/ (excluding .env*, .git/, .ssh/, .vite/, .DS_Store), encrypts the archive with FIPS KEM-DEM using the deployment public key, uploads to the signed URL, then uploads any client assets (CDN-bound) with up to four concurrent requests.
10. Provision. Calls projectDeploymentComplete to start server-side provisioning.
11. Poll status. Up to 300 seconds, optionally streaming warmup logs from the deployment's stream URL.

When provisioning completes, the CLI prints a banner with the deployment URL, the project's "latest" URL, the dashboard URL, and any custom domain URLs you configured.

{ "scripts": { "deploy": "agentuity deploy" } }

npm run deploy

Read the Output

The banner is the canonical source for the deployed URL. The output shape looks like this:

[OK] Your project was deployed!
 
Deployment: deploy_abc123...
-> Deployment: https://<deployment-host>.agentuity.run
-> Project:    https://<project-host>.agentuity.run
-> Dashboard:  https://app.agentuity.com/r/deploy_abc123...

The same values are reachable later through project show:

agentuity project show <project-id>

The output includes urls.app (public URL of the latest deployment), urls.dashboard, and urls.custom (when a custom domain is attached).

Validate Before and After Deploy

agentuity project import --validate-only        # confirm directory shape
agentuity build --report-file report.json       # confirm framework detection and bundle output
agentuity deploy --message "validation check"   # ship
curl https://<vanity-url>/                       # exercise the running deploy

Use the build report when something fails non-obviously: it captures TypeScript errors with file paths and line numbers, build phase timings, and warnings. The deploy banner gives you the URL; a quick curl or browser load confirms the platform actually started the process.

Recover Common Failures

Operate a Deployment

These commands work against deployments after they ship.

List, Show, and Read Logs

agentuity cloud deployment list                       # 10 most recent, latest first
agentuity cloud deployment list --count 50            # up to 100
agentuity cloud deployment show <deployment-id>       # full metadata
agentuity cloud deployment logs <deployment-id>       # most recent 100 lines
agentuity cloud deployment logs <deployment-id> --limit 500 --no-timestamps

cloud deployment show surfaces:

• Deployment ID, project ID, state (completed, failed, pending), active flag, tags
• Region, custom domains, attached database/storage resource names
• Deployment Logs and Build Logs URLs (open in dashboard for live tailing)
• Git metadata (branch, commit, message, provider)
• Build metadata (Agentuity CLI version, Bun version, platform, arch)

Roll Back

agentuity cloud deployment rollback
agentuity cloud deployment rollback --project-id proj_...

Activates the most recent completed deployment behind the current one. The CLI confirms before switching. The previous active deployment stays at its per-deployment URL but is no longer the project's "latest".

Undeploy

agentuity cloud deployment undeploy
agentuity cloud deployment undeploy --force

Stops the active deployment. The project URL returns 404 until a new deploy ships. Per-deployment URLs continue to resolve; only the active one is paused.

Delete a Deployment

agentuity cloud deployment delete <deployment-id>
agentuity cloud deployment delete <deployment-id> --force

Permanently removes a single deployment from the project's history. The deployment URL stops resolving.

Delete a Project

agentuity project delete                              # interactive multi-select
agentuity project delete <project-id>
agentuity project delete --confirm                    # CI-safe, no prompt

Deletes the project record, all its deployments, and breaks the local agentuity.json link. There is no recovery.

Machines

agentuity cloud machine (alias machines) lists and manages the underlying compute that runs your deployments. Most users never touch these. They exist for capacity inspection and emergency teardown.

agentuity cloud machine list
agentuity cloud machine list --org-id org_...
agentuity cloud machine show <machine-id>
agentuity cloud machine deployments <machine-id>
agentuity cloud machine delete <machine-id> --confirm

machine show surfaces the instance type, availability zone, private IPv4, and the deployments currently scheduled on it.

Lifecycle Scripts

agentuity deploy runs the deploy command directly. Wrap it in a package script when you want lifecycle hooks:

{
  "scripts": {
    "predeploy": "npm run typecheck",
    "deploy": "agentuity deploy",
    "postdeploy": "npm run notify-team"
  }
}

npm run deploy

When the GitHub App runs the deploy in its build environment, it honors the same predeploy and postdeploy script slots. See Pre-Deploy Scripts for the CI-side behavior.

Automating with the GitHub App

For repository-driven deploys, link the repo with the Agentuity GitHub App:

agentuity git link --branch main --deploy --preview

Pushes to the linked branch trigger a deploy. Pull requests get isolated preview environments that auto-cleanup on close or merge. The build runs from a clean checkout in Agentuity's environment, not from your laptop, and the App passes git metadata (commit, branch, repo, PR number) to deploy as flags.

See Automating Deployments with the GitHub App for the full lifecycle, Push Deploys for branch deploys, and Preview Environments for PR builds.

Coming from a Legacy Project

For projects on the older deploy path, inspect the migration CLI before changing anything:

npx @agentuity/migrate --help

Use the migration command to inspect the changes needed before moving an existing project onto the latest CLI. Keep legacy projects on their existing deploy path until you have run the migration and checked the new build.

Next Steps

• Custom Domains: attach your own domain, set DNS, verify TLS.
• Environment Variables: how .env values become cloud project vars and secrets.
• Local Development: iterate against the same project before shipping.
• Deployment Bundle Contents: full file inventory of .agentuity/.
• Deploy Options: every flag accepted by agentuity deploy.
• Runtime and Build Resources: adjust CPU, memory, and disk in agentuity.json.