---
name: bijection-boxd
description: "Evaluate and integrate the Boxd component with Bijection."
---

# Boxd

Composable computer lifecycle

- Package: @bijectionhq/boxd
- Category: Sandboxes
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/boxd/tree/21bc278b78c75f22af60d6e77624e41121af9e28
- Upstream: https://github.com/azin-tech/boxd-convex/tree/1061d4021dac2fbebd1717beb3c6124c7cbb6850
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/boxd

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/boxd.git
cd boxd
git checkout 21bc278b78c75f22af60d6e77624e41121af9e28
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @boxd-sh/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses boxd. Follow the installation and configuration steps exactly.

# boxd

## Instructions

The boxd Convex component lets you create, fork, and control full Linux microVMs from Convex actions, with machine state and command output stored in reactive Convex tables. It wraps the boxd API to handle authentication token management, owner-scoped access control, and idempotent lifecycle operations including pause, hibernate, wake, stop, and destroy. Queries over machine rows and execution history re-run automatically when state changes, so your UI stays current without polling.

### Installation

```bash
npm install @boxd-sh/convex
```

Current npm version: `@boxd-sh/convex@0.1.1`

## Use cases

- Building AI coding agents that need isolated Linux environments to run arbitrary code, install packages, and persist state between steps
- Spinning up per-user or per-tenant sandboxed compute environments where each user gets their own microVM scoped to their identity
- Running long-lived background processes on a machine and checking output later with subsequent exec calls, working around Convex's 10-minute action limit
- Forking a known-good machine state as a starting point for each task, similar to branching a git repo, to avoid cold setup time
- Exposing a port from a microVM to a stable public HTTPS URL so a Convex-backed app can serve web traffic directly from a machine

## How it works

Install the component and register it in `convex/convex.config.ts` using `app.use(boxd, { env: { BOXD_API_KEY: app.env.BOXD_API_KEY } })`. The API key is bound into the component's own environment so it never appears as a function argument. The component exchanges the key for a session token once, stores it in its own table, and reuses it across actions to avoid hitting boxd's rate limit on token exchanges per source IP.

Instantiate `Boxd` with `new Boxd(components.boxd)` in your convex functions file. Methods like `create`, `fork`, `exec`, `pause`, `hibernate`, and `destroy` run in Convex actions and call boxd through the `@boxd-sh/sdk` web entry. Read methods like `list`, `get`, `listExecutions`, and `getExecution` run in queries and return reactive data directly from the component's tables.

Every machine is addressed with both a `machineId` and an `ownerId`. Passing a mismatched owner returns `NOT_FOUND`, the same as a nonexistent machine, which enforces tenant isolation without extra guards. Errors are typed `ConvexError` values with a `code` field, and the exported `isBoxdError` helper lets you branch on specific codes like `NOT_FOUND`, `CONFLICT`, or `TIMEOUT`.

Machine rows update immediately when a component call changes state, but boxd can also change machines out-of-band, for example via `autoSuspendSeconds`. Call `refresh` on a timer to sync those external state changes back into the reactive table.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by boxd is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40boxd-sh%2Fconvex)
- [GitHub repository](https://github.com/azin-tech/boxd-convex)
- [Live demo](https://convex-demo.boxd.sh)
- [Convex Components Directory](https://www.convex.dev/components/boxd-sh/convex)
- [Convex documentation](https://docs.convex.dev)