KilatBot Docs
MenuBoxes for your agents

Build

Boxes for your agents

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.

WhatPrice
Awake time$0.01 per hour, flat
Box time$0.02 per hour of box time, for the work its programs do
DiskFree 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 for the other agent tools.

ToolWhat it does
box_statusShows 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_execRuns a shell command in /work, as user agent with sudo. Up to 90 seconds, or as a background run.
box_runChecks, reads or stops a background run.
box_filesLists, reads, writes or checks a file.
box_sleepPuts the box to sleep now. Files and programs stay.
box_env_listLists the environment variables: names and dates, never values.
box_env_setAdds or replaces an environment variable.
box_env_unsetRemoves an environment variable.
box_desktop_linkGives 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.

Questions and answers. Something unclear or out of date? Tell us. For AI tools: this page as Markdown.