> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirage

> Run the programs a Mirage workspace captures on a boxd machine you created, in Python or TypeScript.

![The Mirage logo mark and wordmark inside the boxd card.](https://mintcdn.com/azin/YgZNOc02fe3RwN8T/images/boxd-x-mirage.png?fit=max\&auto=format\&n=YgZNOc02fe3RwN8T\&q=85\&s=7f6c6537662a0a75256196afa42ae8a3)

[Mirage](https://docs.mirage.strukto.ai), 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](https://github.com/strukto-ai/mirage/pull/2234)). 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](https://docs.mirage.strukto.ai/home/setup/machine/boxd).

> [!NOTE]
>
> 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](https://github.com/strukto-ai/mirage).

## Set up

**1. Install from a checkout**

The Python package builds a Rust extension, so you need [Rust](https://rustup.rs) and [uv](https://docs.astral.sh/uv/):

```bash theme={"theme":"github-dark"}
git clone https://github.com/strukto-ai/mirage
uv venv -p 3.12
uv pip install './mirage/python[boxd]'
```

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**

```bash theme={"theme":"github-dark"}
boxd auth keys create mirage --org <your-org>
export BOXD_API_KEY=bxd_...
```

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**

```python mirage_boxd.py theme={"theme":"github-dark"}
import asyncio

from boxd import AsyncBoxd
from mirage import RAMVFS, MountMode, Workspace

TOTAL = "import sys; print(sum(float(line.split(',')[1]) for line in list(sys.stdin)[1:]))"


async def main() -> None:
    boxd = AsyncBoxd(region="fra")
    machine = await boxd.machines.create("mirage-box", isolated=True)
    await boxd.machines.wait_until_ready(machine.id)

    ws = Workspace(
        {"/data": RAMVFS()},
        mode=MountMode.EXEC,
        machines={
            "box": {
                "provider": "boxd",
                "machine_id": machine.id,
                "region": "fra",
                "captures": ["@python", "@external"],
            }
        },
    )
    try:
        await ws.shell("cat > /data/points.csv", stdin=b"name,value\nalpha,1.5\nbeta,2.5\ngamma,4.0\n")
        for line in [
            "python3 -c 'import platform; print(platform.node())'",
            f'cat /data/points.csv | python3 -c "{TOTAL}" > /data/total.txt',
            "cat /data/total.txt",
        ]:
            result = await ws.shell(line)
            print(f"$ {line}\n{await result.stdout_str()}", end="")
    finally:
        await ws.close()
        await boxd.machines.delete(machine.id)


asyncio.run(main())
```

```bash theme={"theme":"github-dark"}
.venv/bin/python mirage_boxd.py
```

```text theme={"theme":"github-dark"}
$ python3 -c 'import platform; print(platform.node())'
mirage-box
$ cat /data/points.csv | python3 -c "import sys; print(sum(float(line.split(',')[1]) for line in list(sys.stdin)[1:]))" > /data/total.txt
$ cat /data/total.txt
8.0
```

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

| Machine field | Default |
| - | - |
| `provider` | `"boxd"` |
| `machine_id` | Required. The id of a machine you created with the CLI, the console or the SDK |
| `api_key` | `BOXD_API_KEY`; a value or a Mirage credential pointer |
| `region` | `BOXD_REGION`, then your account's default [region](https://docs.boxd.sh/guides/regions.md); `fra` or `nyc` |
| `captures` | `@external`, every program Mirage does not have itself. Add `@python` to run Python on the machine |

In TypeScript the fields are `machineId` and `apiKey`, and you install `@boxd-sh/sdk` next to `@struktoai/mirage-node`. Mirage's [boxd page](https://docs.mirage.strukto.ai/home/setup/machine/boxd) 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](https://docs.boxd.sh/guides/suspend-resume.md) 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](https://docs.boxd.sh/use-cases/sandboxes.md#cut-off-from-your-fleet-by-design).
* **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

* [boxd in Mirage's docs](https://docs.mirage.strukto.ai/home/setup/machine/boxd)
* [The example in Mirage's repository](https://github.com/strukto-ai/mirage/blob/main/examples/python/machine/boxd/boxd_workspace.py)
* [Mirage on GitHub](https://github.com/strukto-ai/mirage)
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.