# Boxes

> Create a Box, an app that lives in a Space with its own code and an always-on machine, then deploy, resize, stop or delete it.

Source: https://docs.whorl.work/boxes

A Box is an app that lives in a Space, with its own code and its own machine that stays on. People and agents in the Space can change the app, and everyone in the Space can open it. Use a Box for an internal tool that should keep running after any Thread ends, such as a scheduling form or a team dashboard. A [Portal](/portals) only lasts as long as one Thread's Environment.

> **Boxes** appears in the sidebar only when your company has Boxes on. If you do not see it, Boxes are not on for your company yet.

A Box belongs to one Space for good, and does not depend on any Thread, Captain or run. The machine keeps running when nobody is using the app. "Always on" means Whorl keeps the app process supervised and never stops it for being idle. It does not promise zero downtime.

## Create a Box

1. Open **Boxes** in the sidebar.
2. Choose **New Box**.
3. Enter a **Name** and choose a **Size**.
4. Choose **Create Box**.

Whorl sets up the Box's code and machine, and the Box shows **Its code repository is being set up** until it is ready. If the page says **New Boxes are off**, an owner or admin has to allow Box sizes first. They do that in **Settings → Company → Agents**, in the Boxes section, under **Boxes can run on**. With no size chosen, new Boxes stay off.

## Change the app

You change a Box's code through a Thread or Captain. Ask in a Thread, for example "Add a column for the supervisor to the schedule form in the Field operations Box". The agent edits its own copy of the code, saves the result to the Box's main version, and asks to deploy it. Saving and deploying are separate steps, so the live app keeps running the previous version until a deploy succeeds.

Open a Box's **Code** view to read its files. A file that is binary or larger than 256 KB is not shown there.

## Deploy

The Box page shows what is live and whether main has changes that are not live yet. Choose **Deploy main** to put the latest code live, or **Redeploy** to deploy again. The **Deployment log** shows each deploy. If a build fails, the previous version stays live.

To open the running app, choose **Open app**. Allow pop-ups for Whorl if your browser blocks the new tab.

## Start, stop, restart and resize

| Action      | What it does                                                         |
| ----------- | -------------------------------------------------------------------- |
| **Start**   | Starts a stopped Box.                                                |
| **Stop**    | Stops the app and its machine.                                       |
| **Restart** | Restarts the app. It is briefly unavailable.                         |
| **Resize**  | Moves the Box to a new size. It restarts and is briefly unavailable. |
| **Delete**  | Removes the app, its code and its machine for good.                  |

The list at the top of **Boxes** filters by status: running, stopped or failed.

## Who can use a Box

Everyone in the Space can open the Box and its app, with their own Whorl sign-in. The Box's own sign-in, if the app has one, is separate from Whorl's.

## For developers

The `whorl boxes checkout` command clones a Box's code to your computer, and `whorl boxes push` puts your last commit on the Box's main. See [The whorl command](/reference/cli).