Skip to main content
The Mirage logo mark and wordmark inside the boxd card. Mirage, by Strukto AI, is a virtual terminal for AI agents. It puts files from many services behind one filesystem and sends each command to the machine that fits it: a container, a microVM, a cloud sandbox or an SSH host. boxd is one of those machines (pull request). You create a boxd machine and give Mirage its id. Mirage then runs the programs it captures, such as python3, on that machine, while the workspace files stay in Mirage. It works from Python and TypeScript, and Mirage’s docs have a boxd page.
The boxd provider is merged into Mirage’s main branch. It is not in a release yet: Mirage 0.0.8 (mirage-ai on PyPI, @struktoai/mirage-node on npm) and the 0.0.9 alphas came out before the merge. It ships with the next release, as the mirage-ai[boxd] extra. Until then, install it from a checkout of strukto-ai/mirage.

Set up

1

Install from a checkout

The Python package builds a Rust extension, so you need Rust and uv:
The first build takes about 10 minutes on 4 vCPUs. The boxd extra installs the boxd Python SDK. Once Mirage ships a release, pip install 'mirage-ai[boxd]' is all you need.
2

Create an API key

Mirage and the SDK read BOXD_API_KEY. You can also set api_key in the machine’s config.
3

Create a machine and run commands on it

mirage_boxd.py
The whole run took about 4 seconds: create the machine, three lines, and delete.
python3 ran on the boxd machine. cat and the /data files stayed in Mirage: the CSV went to the machine on stdin, and the answer came back into the workspace.

Configuration

In TypeScript the fields are machineId and apiKey, and you install @boxd-sh/sdk next to @struktoai/mirage-node. Mirage’s boxd page has the TypeScript and YAML versions.

The machine is yours

  • Mirage never creates, stops or deletes it. Closing the workspace leaves the machine as it is. Delete it yourself when you are done, as the example does.
  • It wakes on the first command. A machine in standby or hibernated wakes when Mirage runs a line on it.
  • State stays between lines. Files on the machine’s disk and background processes survive from one line to the next.
  • A stopped or deleted machine makes a line exit 1, with an error that says how to fix it.
  • Isolated is a good fit. isolated=True keeps the machine off your organization’s network and away from its credentials, which suits programs an agent writes. See sandboxes.
  • boxd settings stay boxd settings: size, region, networking and idle timers. Put the files the programs need on the machine yourself, or pass them on stdin.

Read more