deploying-boxes

Installation
SKILL.md

Deploying to Boxes

A Box is an always-on Google Compute Engine machine owned by a user or a workspace. It runs one Amp runner and hosts several independently deployed apps, called deployments. Each deployment has its own repository, branch, port, secrets, data directory, and URL, https://<deployment>--<namespace>.onamp.dev. A router on the Box listens on port 8080 and sends each URL to its deployment's port.

A Box selector is <namespace>/<box>. The namespace picks the owner: the user's username for a personal Box, or the name of a workspace the user belongs to for a workspace Box. Choose the deployment name separately with --name. Deployment names share the owner's URL namespace, so a deployment name must not match any of the owner's Box names or a deployment on another of the owner's Boxes.

Boxes were called perma-orbs before they were renamed, with no compatibility aliases. amp perma-orbs, .amp/perma-orb.yaml, .amp/perma-orb-deploy.json, and amp secrets --perma-orb no longer work; use amp boxes, .amp/box.yaml, .amp/box-deploy.json, and amp secrets --box. Rename old files in a repository instead of keeping both. Hosted Apps and obelisks were removed too: amp apps ..., .amp/obelisk.yaml, and amp secrets --app no longer exist.

Where work happens

  • Develop, commit, push, and deploy from an ordinary orb thread on the app's repository. amp boxes deploy builds the release where it runs and only works on Linux x64; it refuses to run on macOS. If the CLI says this version builds on the Box and is no longer supported, run amp update and deploy again.
  • Deploys use pushed Git code. The CLI shallow-clones the tip of the deployed branch into a temporary directory, builds there, and uploads the result. The Box unpacks it into a new release and switches to it; the Box never builds. Uncommitted or unpushed files never reach the Box, and the orb's .amp/services.yaml dev servers are unrelated.
  • Start a thread on the Box only for live production work, such as reading service logs, inspecting or repairing live data, or an urgent fix to the running app. A live thread can change files and data for every deployment on the Box.

Before deploying

Installs
1
GitHub Stars
21
First Seen
Nov 4, 2026