Boxes

A box is an always-on computer on which you can run all the things you’ve built with Amp. Websites, dashboards, tools, long-running services. Each one gets its own URL.

Built something in orbs but now want to always have it available? Put it in a box.

Boxes are small and cheap. Most of the software we build nowadays doesn’t need 16 CPU cores all day, every day.

The smallest box has 2 GB of memory and costs about $18 a month. You can also tell Amp to turn it off overnight, in case you only need it when you’re awake.

You do not need to set anything up. Ask Amp to deploy your app to a box, and the agent creates the box, builds your app, and gives you its URL. When something needs to change in the live app, you start a thread on the box.

How It Works

1. You build your software in orbs or in runner threads. Once it’s ready, ask the agent to deploy it to a box. It will create a box for you.
2. Once the box is up, the agent runs amp boxes deploy. A release is built inside the orb, or on the runner’s machine, and sent to the box.
3. The box then runs the release and serves it at the app’s own URL, such as https://bug-tracker--acme.onamp.dev. One box can run many apps.
4. Each box runs an Amp runner. You can start a thread on the box to check logs, fix data, or change the app while it runs.

Every box is an Ubuntu 24.04 machine with a 20 GB disk, in one of four sizes. Files and data on the disk stay there across deploys and restarts.

Deploy an App

Tell the agent in your thread what you want:

The agent writes a .amp/box.yaml file if the repository does not have one, pushes the code, and runs amp boxes deploy. The first deploy can create the box for you, which can take a few minutes. You can also run the commands yourself from a Git checkout in an orb:

amp boxes deploy --on alice/workbench --name bug-tracker --create

alice/workbench is the box: your username, or a workspace name, and the box name. bug-tracker is the app name, which becomes part of the app’s URL. After the first deploy, Amp saves the target in .amp/box-deploy.json, so later deploys need no flags:

amp boxes deploy

The file can hold several targets, such as staging and production. Then name the one to deploy, for example amp boxes deploy staging, or run the command inside an app’s folder.

.amp/box.yaml says how to build the app, which files to ship, and which services to run:

build: pnpm install --frozen-lockfile && pnpm build
source: false
artifacts: [build, package.json]
services:
  web:
    command: node build

Here is what happens during a deploy:

• Amp runs build on the pushed branch where the command runs, usually an orb. Push your changes first, because uncommitted and unpushed files never reach the box.
• When your checkout is at the pushed commit, has no uncommitted or untracked files, and the config lists artifacts, build runs in that checkout and reuses its installed dependencies and build caches, as if you ran it yourself. Otherwise Amp builds in a fresh clone of the branch.
• Amp packs the artifacts and sends them to the box as a new release.
• The box switches to the new release and restarts the app’s services.
• Amp waits for the app to listen on its port. If it does not, the box switches back to the previous release and the deploy fails.

The box keeps the live release and the two releases before it. Your server should listen on the port in the PORT environment variable. Amp also sets AMP_DEPLOYMENT_URL to the app’s URL, AMP_DEPLOYMENT_NAME to the app name, AMP_DEPLOYMENT_BOX to the box (alice/workbench), and AMP_DEPLOYMENT_DATA_DIRECTORY to a directory for databases, uploads, and other data that must survive deploys. The build sees the first three, but not the data directory or secrets.

With source: false, the release holds just the artifacts, and every service’s cwd must be inside one of them. Without it, the release also holds the app’s source with its Git history and installed dependencies, so threads on the box can read and change the running code.

Several Apps on One Box

A box can run as many apps as fit on the machine. Deploy another repository to the same box with a different app name:

amp boxes deploy --on alice/workbench --name tiny-crm

Every app gets its own URL, its own services, its own secrets, and its own data directory. Each app’s services run as the app’s own Linux user, in a systemd sandbox. An app cannot use sudo or install packages. It sees only its own folder under /home, cannot change its release, and can write only to its data directory and its home directory. It cannot read the other apps’ files, secrets, or processes.

This separates the apps’ files, but it is not a security boundary between them. The apps share the box’s CPU, memory, disk, network, and the software installed on it, with no limit per app. An app can connect to the other apps’ ports and to services on the box, such as a database you installed. Only put apps on the same box if you would trust each of them with the others’ data. Use a separate box for an app you do not trust.

An app stays tied to the repository it was first deployed from, and a deploy from another repository is refused. To move an app, for example into a monorepo, deploy it from the new checkout with --move. It keeps its URL, data, secrets, and privacy setting:

amp boxes deploy --on alice/workbench --name tiny-crm --move

A commit made in the live release on the box blocks the move unless the new repository’s branch contains it.

Several Apps in One Repository

Each app in a repository is a folder with its own .amp/box.yaml. The app’s build runs in that folder, and its service cwd and artifacts are relative to it. The repository root can be an app too. Run each app’s first deploy from inside its folder:

cd crm
amp boxes deploy --on alice/workbench --name tiny-crm
cd ../status
amp boxes deploy --on alice/workbench --name status

Amp deploys the app whose .amp/box.yaml is nearest to the current directory. It saves a target named after the folder, with the folder as root, in .amp/box-deploy.json at the repository root:

{
	"targets": {
		"crm": { "on": "alice/workbench", "name": "tiny-crm", "root": "crm" },
		"status": { "on": "alice/workbench", "name": "status", "root": "status" }
	}
}

After that, amp boxes deploy inside a folder deploys that folder’s app, and amp boxes deploy crm works from anywhere in the checkout. An app remembers its folder, so a deploy of another folder into it is refused unless you pass --move.

An app’s release holds only its folder and the files at the repository root, such as a workspace lockfile, so the other apps’ files never reach its box. The build sees only those paths too. List any other folders the app needs, such as shared packages, under include, relative to the app’s folder:

build: pnpm install --frozen-lockfile && pnpm --filter crm build
include:
  - ../packages/ui
services:
  web:
    command: node build

Boxes and Orbs

Orbs and boxes are both machines that Amp runs for you, but you use them for different work.

The usual workflow uses both. You build and review a change in an orb, then deploy it to a box. A box never builds code itself. A thread on a box runs on the box’s Amp runner and works on the live app, so use an orb when you want to review a change before it goes live.

Personal and Workspace Boxes

A box belongs to you or to a workspace. The first part of its name says which:

• alice/workbench is a personal box. Only you can see it, deploy to it, and start threads on it.
• acme/workbench is a workspace box in the acme workspace. Every member of the workspace can see it, deploy to it, and start threads on it. Only the member who created it and workspace admins can delete it, start or stop it, change its schedule, and see what it costs.

Every member can run code on a workspace box, so do not keep anything on it that a member should not see. Workspace boxes need an Enterprise workspace or a Teams workspace with a payment method.

If an account is suspended, Amp stops its personal boxes until the account is unsuspended. A workspace box whose creator is suspended keeps running for the workspace, but its URLs and apps are offline until then. Deleting an account deletes its personal boxes with their data.

A multiplayer thread, including every thread a Space starts, can list, inspect, deploy to, and run commands on the workspace boxes of its own workspace, because everyone who can prompt it is a member. It cannot use personal boxes or boxes of other workspaces, create boxes, or do what only a box’s creator or a workspace admin can do. Do those from a thread that is not multiplayer.

Workspace admins can turn off Allow Users to Create Boxes in the workspace’s Boxes settings. Members then cannot create workspace boxes or personal boxes. Boxes that already exist keep running.

Public and Private Apps

An app’s URL is public by default, so anyone with the URL can open it. To limit an app to the box’s owner, or to members of the workspace that owns the box, deploy it with --private:

amp boxes deploy --private

People then sign in to Amp in their browser before the app opens. Requests without that sign-in, such as webhooks, cannot reach a private app. Later deploys keep the setting, and Amp saves it on the app’s target in .amp/box-deploy.json, so a deploy from a fresh checkout that creates the app again makes it private too. Deploy with --public to make the URL public again.

Amp does not tell your app who opened it. If your app needs to know who the user is, or if it is public, it has to handle sign-in itself.

Feedback Widget

Deploy an app with --widget and Amp adds the feedback widget to its pages. The app needs no script tag or code for it:

amp boxes deploy --widget

People point at part of a page and write what they want changed. Amp then starts a thread on the box to change the live app, or in an orb to change its code. On a private app the widget shows to everyone who can open the app. On a public app it starts hidden: press Cmd+. (Ctrl+. on Windows and Linux), or tap three times quickly on a phone, to show it. Sending a comment always needs an Amp sign-in as the box’s owner or a member of the workspace that owns it. Later deploys keep the setting; deploy with --no-widget to remove the widget. If your site already loads a project’s feedback widget script, you can keep it: on a box app it gives way to this widget.

Custom Domains

An app can use a hostname on your own domain instead of its onamp.dev URL. First add the domain on the Domains page of the box owner’s personal or workspace settings, create the DNS records shown there, and wait until the domain is Active. Then deploy with the hostname, which can be the domain itself or a direct subdomain of it:

amp boxes deploy --domain portal.example.com

The app’s onamp.dev URL then redirects to the new hostname, and the app sees it in AMP_DEPLOYMENT_URL. Private apps, the feedback widget, and the app’s pane in Amp work the same on the new hostname. If the app uses Sign in with Amp, add a redirect URL on the new hostname to its OAuth client. Amp saves the hostname on the app’s target in .amp/box-deploy.json, so later deploys keep it. Deploy with --no-domain to serve the app at its onamp.dev URL again.

To move a hostname that a thread portal uses today to a box app, deploy the app once without --domain and check it, then deploy again with --take-over:

amp boxes deploy --domain portal.example.com --take-over

The hostname switches to the live app as soon as the deploy starts, so people who have the link never reach an empty app. A thread portal cannot take a hostname back from a box app.

Reporting Abuse

Box apps must follow Amp’s Acceptable Use Policy. To report an app on onamp.dev or on a custom domain that serves phishing, malware, or other abuse, email security@ampcode.com with its URL.

When a box breaks the policy, Amp can block it. A blocked box stops, and every URL of it, including its apps, private apps, and custom domains, shows a page saying the app is unavailable. Its disk and data are kept. It stays stopped, even through its run schedule, until Amp unblocks it, and its owner cannot start it. Amp emails the box’s owner, or the workspace admins and the box’s creator for a workspace box, with the reason, and the box’s page in Amp shows it. Reply to that email once you have fixed the problem. When Amp unblocks the box, it starts again unless it was stopped for another reason.

Start a Thread on a Box

Open the box in the app and click the new thread button beside an app, or the one at the top of the page for the whole box. With a mouse, the button beside an app appears when you point at the app’s row. Amp asks you to confirm, because the thread works on the live app and its data, then opens the composer with the box selected.

You can also choose a box in the composer. Click the executor at the bottom left, find the box under Boxes, and choose Machine or one of its apps.

A thread on an app opens in the app’s live release. An app deployed with source: false, as in the example .amp/box.yaml, has no code on the box to read or change. The thread works with the app’s data, logs, and services; change its code in an orb and deploy again.

To change the running code from a thread on the box, leave out source: false. The release then holds the app’s source with its Git history, and the app picks up changed files when its services restart. A later deploy refuses to drop changes made on the box. Commit them in the live release and push them to the deployed branch, or discard them with the command the deploy prints.

Install Software

Threads on a box and amp boxes exec run as the box’s user account, which has sudo. You can install system packages and services the same way as on any Linux server, or ask the agent:

Software installed this way stays across deploys and restarts, and every app on the box can use it. Services such as Redis or Postgres listen on the box’s localhost, where every app can reach them, so give each app its own database user and password. You can also install Docker and run containers. Containers run outside the apps’ sandbox, so run only images you trust.

Apps cannot install software themselves. To give an app its own version of a runtime, such as a Node.js or PHP version the box does not have, download it in the app’s build and ship it as an artifact. Two apps on one box can then run different versions:

build: |
  mkdir -p runtime
  curl -fsSL https://nodejs.org/dist/v22.23.4/node-v22.23.4-linux-x64.tar.xz |
    tar -xJ -C runtime --strip-components=2 node-v22.23.4-linux-x64/bin/node
source: false
artifacts: [runtime, server.mjs]
services:
  web:
    command: ./runtime/node server.mjs

Boxes have no public IP address, so you cannot SSH into one. Start a thread on the box instead, run a command with amp boxes exec, or copy files with amp boxes cp.

Manage Your Boxes

Open Boxes in the app’s navigation to see every box you can use:

• The sidebar lists your boxes with each box’s number of apps and its latest deploy. Your personal boxes are under Personal. Workspace boxes are under Workspace, or under each workspace’s name if you belong to more than one.
• Overview shows recent deploys and threads across all your boxes.
• Each box has its own page. It lists the box’s apps with their URLs, the recent activity, and a chart of threads and uptime. The About panel shows whether the box is running, its schedule, its size, and, if you can manage the box, what it cost this month and what it will cost by the end of the month.
• New Box opens the composer with a request for a new box. Amp asks what you want to host and creates nothing until you send the message.

If you can manage the box, the menu at the top right of its page has Start Box or Stop Box, and Delete Box. Deleting a box deletes all its apps and their data, so keep backups of anything you cannot lose.

Sizes and Pricing

You pay for every minute a box runs. A stopped box costs nothing.

b1.tiny and b1.small share their CPUs: each can use 2 vCPUs for short bursts and uses the amount in the table the rest of the time. Every size has a 20 GB disk. b1.small is the default. A box that runs all month costs the 30-day price in a 30-day month and a thirtieth more in a 31-day month. A run schedule lowers the price. This is what 30 days cost when the box runs some hours a day, such as 18 hours from 05:00 to 23:00:

Who pays depends on the owner:

• A workspace box is paid by its workspace.
• A personal box is paid by your workspace if you were a member of one when you created the box, and by your personal credits otherwise. This is the same as for orbs. If you leave the workspace or are removed from it, your personal credits pay for the box from then on.

Box usage counts against your plan’s included usage and then your credits. Amp Free’s daily credits do not pay for boxes. Enterprise workspaces pay for boxes at their Amp orb rate.

Creating a box needs at least $2 of credits, the same as starting an orb. If the payer runs out of credits, Amp sends an email, and the box stops 24 hours later. Its disk and data are kept, and it starts again a few minutes after credits are added.

Each box can send 100 GB of network traffic a month, counting everything its apps serve. Amp emails you at 80 GB. At the limit, Amp stops the box until the next month (UTC) starts. Contact Amp support if a box needs more.

Choose a Size

Tell the agent which size you want when it creates the box, or pass --size yourself. A new box without --size is b1.small. Amp keeps spare b1.tiny and b1.small machines ready. A new b1.medium or b1.large box waits about 6 minutes while Amp starts its machine.

amp boxes create alice/tools --size b1.tiny
amp boxes deploy --on alice/tools --name status --create --size b1.tiny

You cannot change the size of an existing box. To move your apps to another size, create a new box of that size and deploy your apps to it. Then copy each app’s data with amp boxes cp, first from the old box to your checkout and then from your checkout to the new box, and delete the old box.

Run Schedules

A box runs all the time unless you give it a schedule. A schedule is one daily window when the box runs. Outside the window, Amp stops the box. Its disk and data are kept, but its apps do not serve requests and threads on it stop until it starts again.

To set a schedule, ask Puck or an agent:

You can also run the command yourself:

amp boxes schedule alice/workbench --on 05:00 --off 23:00 --tz Europe/Berlin

The times are local times in the time zone you give, so the schedule follows daylight saving time. An --off time earlier than --on keeps the box on overnight. To remove the schedule and keep the box on all the time, run amp boxes schedule alice/workbench --clear. Agents use the manage_amp tool with topic boxes and operation set-schedule or clear-schedule instead.

The box page shows the schedule and what the box will cost this month under it. You cannot edit the schedule on the page.

To start or stop a box right away, use Start Box or Stop Box on its page, or run amp boxes start or amp boxes stop. Agents use the manage_amp tool with topic boxes and operation start or stop. The box stays that way until the schedule’s next start or stop time. At a scheduled stop, Amp waits up to 30 minutes for running threads and deploys to finish, then stops the box.

Rename a Box

To rename a box within its namespace, run:

amp boxes rename alice/workbench tools

The box keeps its apps, their URLs, data, secrets, schedule, and threads. The old name is free right away. Commands, saved deploy targets, and links that use the old name stop working, so update them:

• Run the command in an app’s checkout and it updates .amp/box-deploy.json there. Commit the change so other checkouts deploy to the new name. It also lists other files that still name the old box.
• Each app sees the new name in AMP_DEPLOYMENT_BOX after its next deploy.
• Only the box’s owner, or for a workspace box its creator or a workspace admin, can rename it. A box cannot be renamed while one of its apps is deploying, or moved to another namespace.

Secrets and Data

Store an app’s secrets on the box with amp secrets, and pass the value from a file instead of the command line:

amp secrets set STRIPE_KEY --box alice/workbench --deployment bug-tracker --secret --data-file ./key.txt

Deploy again after you change a secret. The build does not see secrets, only the running app does.

Each app keeps its data in AMP_DEPLOYMENT_DATA_DIRECTORY. The data stays on the box across deploys, but it is deleted with the box, so keep your own backups. To copy a file to or from an app’s data directory, use amp boxes cp:

amp boxes cp alice/workbench:app.db ./backup/ --deployment bug-tracker

Commands

• amp boxes deploy: build the current repository and deploy it to a box.
• amp boxes deployments: list the apps on a box.
• amp boxes undeploy: stop one app and remove its URL.
• amp boxes cancel-deploy: cancel a deploy that is still running.
• amp boxes create: create a box. --size picks its size.
• amp boxes list: list the boxes you can use.
• amp boxes show: show a box, its schedule, and why it is stopped.
• amp boxes exec: run a command on a box.
• amp boxes cp: copy a file to or from a box.
• amp boxes schedule: set or clear the daily run schedule.
• amp boxes start: start a stopped box.
• amp boxes stop: stop a box and keep its disk.
• amp boxes rename: rename a box within its namespace.
• amp boxes delete: delete a box with all its apps and data.

Run amp boxes <command> --help to see each command’s options.