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

# boxd

> Run captured programs on a boxd machine you created.

The `boxd` machine provider reaches a [boxd](https://boxd.sh?ref=mirage)
machine, by ID, and runs the programs it captures on it. A boxd machine is
a full Ubuntu VM with its own kernel and a persistent disk. You create the
machine; Mirage only runs programs on it. Python and Node.

## Installation

> [tab] Python
>
> ```bash theme={null}
> pip install 'mirage-ai[boxd]'
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add @boxd-sh/sdk
> ```

Set `api_key` in the config, as a value or a
[credential pointer](https://docs.mirage.strukto.ai/home/service-credentials.md#pointer-fields), or `BOXD_API_KEY`.
Set `region` (`fra` or `nyc`) to the machine's region, or `BOXD_REGION`;
without either, the SDK looks in your account's default region.

Create the machine with the [boxd CLI](https://docs.boxd.sh/cli/commands?ref=mirage),
the console or the SDK, and pass its ID as `machine_id`:

> [tab] Python
>
> ```python theme={null}
> from boxd import AsyncBoxd
>
> boxd = AsyncBoxd(region="fra")
> machine = await boxd.machines.create("mirage-box", isolated=True)
> await boxd.machines.wait_until_ready(machine.id)
> print(machine.id)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Boxd } from '@boxd-sh/sdk'
>
> const boxd = new Boxd({ region: 'fra' })
> const machine = await boxd.machines.create({ name: 'mirage-box', isolated: true })
> await boxd.machines.waitUntilReady(machine.id)
> console.log(machine.id)
> ```

`isolated` keeps the machine off your organization's private network and out
of reach of its credentials, which suits programs an agent writes.

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python on the machine too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={
>         "box": {
>             "provider": "boxd",
>             "machine_id": "machine-id",
>             "region": "fra",
>             "captures": ["@python", "@external"],
>         }
>     },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: {
>       box: {
>         provider: 'boxd',
>         machineId: 'machine-id',
>         region: 'fra',
>         captures: ['@python', '@external'],
>       },
>     },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: boxd
>     machine_id: ${BOXD_MACHINE_ID}
>     region: fra
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

## Connecting the workspace

boxd takes no `mount_type`. Put the files the programs need on the machine
yourself, or pass them in on stdin.

## The machine's lifetime

The machine is yours: Mirage never creates, starts, stops or deletes it, and
closing the workspace leaves it as it is. A machine in standby or hibernated
wakes on the first line. A machine's processes and disk survive between
lines, so a background job started with `nohup` keeps running.

Once the machine is stopped or deleted, a line exits 1, and its error names
the fix:

```text theme={null}
machine 2c95f55f-... is not running: it was stopped; start it (`boxd machine start`) and run the line again
```

A line that is running when the connection to the machine drops exits 129.
The next line connects again.

## Notes

* Output comes back as the program wrote it, binary included, with stdout
  and stderr apart.
* Piped input reaches the program as it is read. Without piped input, stdin
  starts closed.
* Commands run concurrently, each with its own input and output.
* A Mirage [timeout](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#timeouts) stops every
  process of that run.
* Size, region, networking and the machine's idle timers stay boxd settings.


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