---
name: bijection-boat
description: "Evaluate and integrate the Boat component with Bijection."
---

# Boat

Boat cloud sandboxes (full root Linux VMs) as a Bijection component: reactive state, retry-safe create, exec, files, preview URLs, coding agents.

- Package: @bijectionhq/boat
- Category: Sandboxes
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/boat/tree/4dd9f60f8fbc561b8ff9486bded92bd24962c640
- Upstream: https://github.com/ariana-dot-dev/boat-convex/tree/168ecde17e4d118400f5121132aaecd61e22d416
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/boat

## Get the source

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

```sh
git clone https://github.com/bijectionhq/boat.git
cd boat
git checkout 4dd9f60f8fbc561b8ff9486bded92bd24962c640
```

## 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 @boatdev/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 Boat Sandboxes. Follow the installation and configuration steps exactly.

# Boat Sandboxes

## Instructions

Boat Convex integrates full root Ubuntu VMs into Convex applications, giving each user, job, or agent its own isolated sandbox with persistent disk state, snapshotting, and resume. Sandbox lifecycle state is stored in a Convex table and exposed reactively via queries, so UI can track provisioning through ready to archived without polling. The component wraps the Boat API server-side, keeping credentials out of client code entirely.

### Installation

```bash
npm install @boatdev/convex
```

Current npm version: `@boatdev/convex@0.1.0`

## Use cases

- Building AI coding agents that need a persistent workspace with real toolchains, where each user gets an isolated environment that stops when idle and resumes exactly where it left off
- Running background processes like dev servers or long builds inside a sandbox and streaming their output back through Convex queries
- Forking a configured sandbox as a template to spin up identical environments for new users without reprovisioning from scratch
- Giving end users browser-accessible preview URLs for ports running inside their sandbox, with optional token gating
- Running coding agents like Claude Code or Codex inside a sandboxed VM and following their work through the prompt and events API

## How it works

Install the package and register the component in `convex/convex.config.ts` using `app.use(boat, { env: { BOAT_API_KEY: app.env.BOAT_API_KEY } })`. The API key is bound at the component level and never surfaces to application code or the browser. Set the key with `npx convex env set BOAT_API_KEY boat_...`.

Every sandbox is addressed by an `{ ownerId, key }` pair. The `ownerId` must always be derived from `ctx.auth` inside a Convex function, not passed in from the client. The `create` and `fork` methods use Boat idempotency keys, so retries return the existing sandbox without billing a second one.

The `Boat` class exposes queries (`get`, `list`) that read cached sandbox state from a Convex table, enabling reactive UI with `useQuery`. Mutations that call the Boat API are performed through actions: `create`, `stop`, `resume`, `fork`, `destroy`, `exec`, `spawn`, `readFile`, `writeFile`, `host`, and `prompt`. Background processes are started with `spawn` and polled with `commandStatus`. Coding agent tasks are handed off with `prompt` and tracked through `events` and `promptStatus`.

For multi-tenant scenarios where users drive the sandboxes directly, pass `noEnv: true` to `create` to prevent the sandbox from inheriting account-level secrets, then supply only the specific `env` values that sandbox needs.

## 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 Boat Sandboxes is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40boatdev%2Fconvex)
- [GitHub repository](https://github.com/ariana-dot-dev/boat-convex)
- [Live demo](https://github.com/ariana-dot-dev/boat-convex/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/boatdev/convex)
- [Convex documentation](https://docs.convex.dev)