# Boxes for your agents

Source: https://kilat.host/docs/boxes

A box is a computer your agents use to write code, run programs and browse the web. It keeps its own files and its own browser, and it sleeps when nobody is using it.

## What a box is

- Each box is a Debian Linux machine with **4 vCPU, 8 GB of memory and 20 GB of disk**.
- Boxes are in beta. A workspace can have up to **2 boxes**, and they need an active plan.
- The first box is made the first time an agent that uses boxes needs one. You can add another on the **Boxes** page in the dashboard sidebar. If you don't see Boxes there, they aren't on for your workspace yet.
- Files in `/work` and your home folder stay when the box sleeps. So do the programs you installed.
- Deleting a box removes its files and everything signed in to its browser. You type the box's name to confirm, and it can't be undone.

## Sleep and wake

- A box sleeps by itself after 30 minutes with no commands and almost no CPU use (under 1% of one vCPU). It stays awake while a background run is going, or while a desktop or terminal is open.
- A command sent to a sleeping box wakes it. The agent then sends the command again.
- To sleep now, choose **Sleep** on the box page, or ask the agent. A box can't sleep while a run is going.
- A sleeping box costs nothing.

## What it costs

A box is paid for by use. It isn't part of your plan.

| What | Price |
| --- | --- |
| Awake time | $0.01 per hour, flat |
| Box time | $0.02 per hour of box time, for the work its programs do |
| Disk | Free during the beta |

Box time is how hard the box works. One hour of box time is one vCPU fully busy for an hour, so all 4 vCPUs busy for an hour use 4 hours of box time.

For example:

- An hour awake and idle: $0.01.
- An hour with one vCPU fully busy: $0.01 + $0.02 = $0.03.
- An hour with all 4 vCPUs fully busy: $0.01 + 4 × $0.02 = $0.09.

Box time is charged after each hour. A charge takes your Credits first, then your Balance. Balance pays for a box only when pay-as-you-go is on, up to its monthly cap. A workspace on a card plan pays the listed US dollar prices, from Credits.

### The monthly cap

Each box can use **100 hours of box time a month**, which is $2 at $0.02 an hour. The count starts again on the 1st of each month.

When a box reaches its cap, or when nothing can pay for it, it refuses new commands, file writes and wake-ups. It goes to sleep once its runs end. Runs still going after 10 minutes are stopped. The message says why and when the cap resets. Your files stay.

## How agents use a box

- An agent reaches a box over Kilat MCP, only when its **Use boxes** switch is on. You find the switch on the agent's **Tools** tab.
- Coder agents have Use boxes on. Other agents have it off until you turn it on.
- Customer-facing agents never reach a box.
- The agent that made a box is its home agent. By default, every other agent that uses boxes in the workspace can use it too.
- A command runs for up to 90 seconds. For longer work, the agent starts a background run and checks on it later.
- An agent reads or writes up to 180 KiB of a file per call. It reads a bigger file in parts.
- What a box sends back is marked as untrusted data, so an agent doesn't take orders from it.

### Box tools

These tools appear only on an owner agent's own token, and only when Use boxes is on. See the [MCP reference](https://kilat.host/docs/mcp#agent-only-tools) for the other agent tools.

| Tool | What it does |
| --- | --- |
| `box_status` | Shows the box: asleep or awake, disk, box time used this month against the cap, and the runs going on. With more than one box, it lists them. |
| `box_exec` | Runs a shell command in `/work`, as user `agent` with sudo. Up to 90 seconds, or as a background run. |
| `box_run` | Checks, reads or stops a background run. |
| `box_files` | Lists, reads, writes or checks a file. |
| `box_sleep` | Puts the box to sleep now. Files and programs stay. |
| `box_env_list` | Lists the environment variables: names and dates, never values. |
| `box_env_set` | Adds or replaces an environment variable. |
| `box_env_unset` | Removes an environment variable. |
| `box_desktop_link` | Gives the link to the box's desktop page, for you. It opens only for admins signed in to Kilat. It isn't a sign-in link. |

## What is installed

- An Xfce desktop with Chromium.
- Python 3, Node, Bun, Go, Rust and OpenJDK 21.
- `git` and `gh`.
- The coding tools `omp`, Claude Code, Codex and OpenCode. Sign in to Claude Code, Codex and OpenCode yourself.
- You can install more with `apt` and `sudo`.
- Docker isn't available in a box yet.

## Desktop and terminal

### Desktop

Choose **Open desktop** on the box page to see the box's screen in your browser. Only the workspace owner or an admin can open it. A sleeping box wakes first, and its files stay as they were.

- A session lasts up to 60 minutes and ends after 10 minutes without input. An open desktop keeps the box awake.
- The desktop adds no charge in the beta.
- The key bar above the screen sends **Esc**, **Tab**, **Ctrl**, **Alt** and **Super**. Ctrl and Alt stay held for the next key.
- **Full screen** fills your screen. The desktop fits your window.

### Paste and the clipboard

- Press **Ctrl+V** (**⌘V** on a Mac) to paste from your computer into the box. In the terminal, add Shift: **Ctrl+Shift+V**.
- Text you copy in the box shows in the **Clipboard** panel under the screen. It also goes to your clipboard when your browser allows it.
- If your browser won't share its clipboard, paste your text into the panel and choose **Send to box**.

### Terminal

The box page also has a **Terminal**: a shell in `/work`. A session ends after 10 minutes without input or 60 minutes in all. An open terminal keeps the box awake.

## Environment variables

Environment variables hold settings and keys your programs need. Set them in the **Environment variables** card on the box page, or ask an agent with Use boxes.

- A box can have up to **50 variables**. A value can be up to **8 KiB**.
- A name has letters, digits and `_`, and doesn't start with a digit. Names that Kilat or the shell use aren't allowed, such as `PATH`, `HOME`, `TZ` and anything that starts with `KILAT_`.
- Values are write-only. After you save one, nobody can see it again in Kilat, not even you. An agent sees names and dates only.
- New shells in the box see a change at once, with no restart. Programs already running keep the old value. A sleeping box gets the change when it wakes.
- Every agent that uses the box can read the values from inside it. Put nothing here you wouldn't share with all of them.
- For a secret, set it yourself on the box page. A value an agent sets passes through its model provider.

## Update system

When a newer system is ready, the box page shows **Update available**. Choose **Update system** to get the latest tools and fixes.

- **What stays:** your files in `/work` and your home folder, including browser sign-ins.
- **What goes:** software you installed with `apt` or `sudo`. Install it again after the update.
- Anything running in the box stops. If tasks are running, Kilat asks you first.
- The box sleeps when the update is done. For a week after, its agents are told to reinstall their apt packages.

## Keep it safe

- Every agent that uses a box shares its files and everything signed in to its browser.
- Don't save passwords, payment details or personal accounts in the box browser.
- Environment variables are readable by every agent in the box.

## Frequently asked questions

### Does a sleeping box cost anything?

No. You pay for awake time and for box time, the work its programs do. Disk is free during the beta.

### What happens when a box reaches its monthly cap?

It refuses new commands, file writes and wake-ups, and goes to sleep once its runs end. Your files stay. The count starts again on the 1st of the month.

### Do I lose my files when a box sleeps or updates?

No. Files in /work and your home folder stay. An update removes only software you installed with apt or sudo.

### Can an agent that talks to my customers use a box?

No. Only your own agents with Use boxes on reach a box. Customer-facing agents never do.

### Can I run Docker in a box?

Not yet.
