deploying-boxes
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 deploybuilds 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, runamp updateand 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.yamldev 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.