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

# Migrating from Box to Boat

> Box is now Boat, and what you create in it is a sandbox. Existing Box integrations remain compatible. Here is what to change and how to know you are done.

Box was renamed **Boat** on September 15, 2026. Same product, same account, same machines, same data. Two words replaced one:

* **Boat** is the product: the site, the CLI, the API, your account and plan.
* a **sandbox** is what you create in it: what a "box" used to be. Paths, keys, events and error codes say `sandbox`.

Existing Box endpoints, CLI integrations, SDK packages, environment variables and hosted URLs remain compatible. The retirement policy is not yet settled. The advertised Sunset header is a migration warning, not an implemented shutdown or a promise of permanent support.

## Timeline

| Date           | What happens                                                                                                                                                                                   |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2026-09-15** | Boat ships. Box surfaces keep working and start answering with `Deprecation` and `Sunset` headers; the `box` CLI prints a reminder on every run.                                               |
| **2026-10-31** | Currently advertised Sunset date. Whether and when legacy endpoints, binaries, packages or hosted URLs retire remains a policy decision. No date-based shutdown is implemented by this rename. |

## The rename in one table

|                      | Box (legacy compatibility)                                                | Boat                                                                     |
| -------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Dashboard            | `box.ascii.dev/box/dashboard`                                             | [`boat.dev/dashboard`](https://boat.dev/dashboard)                       |
| Docs                 | `docs.ascii.dev/box/<page>`                                               | `docs.boat.dev/<page>` (every old URL redirects)                         |
| API base             | `https://ascii.dev/api/box/v1`                                            | `https://boat.dev/api/v1`                                                |
| Resource paths       | `/boxes/{boxId}`                                                          | `/sandboxes/{sandboxId}`                                                 |
| JSON keys            | 13 keys, every one listed in the [appendix](#appendix-every-renamed-name) | the same 13 with `sandbox` in place of `box`                             |
| Envelope `type`      | 12 values, [all listed below](#appendix-every-renamed-name)               | `sandbox.` in place of `box.`                                            |
| Error codes          | 17 codes, [all listed below](#appendix-every-renamed-name)                | `sandbox_` in place of `box_`                                            |
| Webhook events       | `box.ready`, `box.error`, `box.archived`, `box.hydrated`                  | `sandbox.ready`, `sandbox.error`, `sandbox.archived`, `sandbox.hydrated` |
| API keys             | `box_...`                                                                 | `boat_...` (keys you already have stay valid)                            |
| Org header           | `X-Box-Org`                                                               | `X-Boat-Org`                                                             |
| CLI                  | `box`, `box-dev`                                                          | `boat`, `boat-dev`                                                       |
| CLI env vars         | 20 variables, [all listed below](#appendix-every-renamed-name)            | `BOAT_` in place of `BOX_`                                               |
| CLI config           | `~/.config/ascii/box/config.json`                                         | `~/.config/ascii/boat/config.json`                                       |
| Snapshot ignore file | `.boxignore`                                                              | `.boatignore`                                                            |
| Hosted URLs          | `https://<label>.on.ascii.dev`                                            | `https://<label>.on.boat.dev` (same route, same token, both answer)      |
| Inside a sandbox     | `box` CLI, `BOX_ID`, `BOX_CURRENT_ID`                                     | `boat` CLI, `BOAT_ID`, `BOAT_CURRENT_ID` (both spellings exported)       |
| Python SDK           | `ascii-box-sdk` / `ascii_box_sdk`                                         | `boat-sdk` / `boat_sdk`                                                  |
| TypeScript SDK       | `@asciidev/box-sdk`                                                       | `@boatdev/sdk`                                                           |
| Rust / Elixir SDK    | `ascii_box_sdk`                                                           | `boat_sdk`                                                               |
| Go SDK               | `github.com/ascii-dev/box-go-sdk`                                         | `github.com/boat-dev/go-sdk`                                             |

**Not changed:** ids (`bx_...`), snapshot ids, the `X-Ascii-*` headers, `Idempotency-Key`, `sandboxId` on API keys (it already said sandbox), and every piece of your data.

## 1. CLI

```bash theme={null}
curl -fsSL https://boat.dev/install | sh      # macOS, Linux
irm https://boat.dev/install.ps1 | iex        # Windows
```

Your login carries over: `boat` reads the config `box` wrote. Then:

* Replace `box` with `boat` in scripts and CI. Subcommands are unchanged: `boat new`, `boat list`, `boat ssh`.
* Rename `BOX_*` variables to `BOAT_*`. An unset `BOAT_*` currently falls back to its `BOX_*` twin with a one-line notice on stderr.
* Rename `.boxignore` files to `.boatignore` (both are currently read; `.boatignore` wins when a directory has both).
* `boat api-key create --box bx_1` is now `--sandbox bx_1`.

The final compatibility release of `box` prints a migration reminder. Move to `boat` for subsequent updates; legacy binaries are not disabled by a date check.

## 2. SDKs

<CodeGroup>
  ```bash Python theme={null}
  pip uninstall ascii-box-sdk
  pip install boat-sdk
  ```

  ```bash TypeScript theme={null}
  npm uninstall @asciidev/box-sdk
  npm install @boatdev/sdk
  ```
</CodeGroup>

Then in your code:

* the import: `ascii_box_sdk` → `boat_sdk`, `@asciidev/box-sdk` → `@boatdev/sdk`
* the base URL: `https://ascii.dev/api/box/v1` → `https://boat.dev/api/v1`
* the client class keeps its product name: `BoxApi` → `BoatApi` (`ascii_box_sdk.api.box_api` → `boat_sdk.api.boat_api`)
* request and response types say sandbox: `CreateBoxRequest` → `CreateSandboxRequest`, `Box` → `Sandbox`, `boxId` → `sandboxId`, `.box` → `.sandbox`, `.boxes` → `.sandboxes`, `deleteBox` → `deleteSandbox`
* the helpers keep their names: Python `wait_until_ready`, `wait_until_idle`, `wait_for_desktop`, `wait_for_prompt`, `wait_for_prompt_done`, `stream_events`, `stream_prompt`, `stop_and_remove`, `read_text`, `write_text`, `exec_command`; TypeScript `waitUntilReady`, `waitUntilIdle`, `waitForDesktop`, `waitForPrompt`, `waitForPromptDone`, `streamEvents`, `streamPrompt`, `stopAndRemove`, `readText`, `writeText`, `execCommand`

A whole-word search-and-replace of `box`/`Box`/`boxes`/`Boxes` → `sandbox`/`Sandbox`/`sandboxes`/`Sandboxes` covers the types and keys; the package import and `BoxApi` → `BoatApi` are the two by hand.

## 3. Raw HTTP

```diff theme={null}
- POST https://ascii.dev/api/box/v1/boxes
+ POST https://boat.dev/api/v1/sandboxes
- Authorization: Bearer box_...      (still accepted)
+ Authorization: Bearer boat_...     (what new keys look like)
```

Responses come back in the new vocabulary: `sandbox` / `sandboxes` / `sandboxId`, `type: "sandbox.created"`, `code: "sandbox_not_found"`. Request bodies use the new keys too (`passSandboxCredentials`, `sourceSandboxId`).

A request to `/api/box/*` currently answers in box vocabulary and carries:

```http theme={null}
Deprecation: @1789430400
Sunset: Sat, 31 Oct 2026 00:00:00 GMT
Link: <https://docs.boat.dev/migrating-from-box>; rel="deprecation"
```

If your client logs response headers, grep for `Sunset` to find the calls you have not moved yet.

## 4. Webhooks

Webhooks you created before the rename keep delivering `box.*` events with `box`-spelled payloads. To move one, create it again through the Boat API (or `boat webhook create`) and delete the old one; the new one delivers `sandbox.*` events and `X-Ascii-Event: sandbox.ready`. Signatures, headers and retries are unchanged.

## 5. Hosted URLs

Every hosted route answers under both `https://<label>.on.ascii.dev` and `https://<label>.on.boat.dev`, with the same `_token`. Update the links you have published or embedded to the `on.boat.dev` form; the retirement policy for the `on.ascii.dev` form remains unresolved.

## 6. Inside a sandbox

The `boat` CLI is on the PATH of every sandbox, and `box` still resolves to it. `BOAT_ID`, `BOAT_CURRENT_ID` and `BOAT_CLI_*` are exported next to their `BOX_*` twins. Agent skills reference the `boat` skill; a `box` skill directory is removed on the next start.

## Am I done?

* No `Sunset` header in your API client's logs.
* No `box` binary invoked by your scripts (the reminder line has stopped).
* `pip show ascii-box-sdk` / `npm ls @asciidev/box-sdk` are empty.
* Webhooks listed by `GET /api/v1/webhooks` show `sandbox.*` events.
* Published links say `on.boat.dev`.

## Appendix: every renamed name

Generated from the API specifications and the CLI source (`backend/src/api/boat/inventory.ts`), so this is the whole list, not a sample. Anything not in these tables did not change.

**API paths**

| Box                                   | Boat                                          |
| ------------------------------------- | --------------------------------------------- |
| `/boxes`                              | `/sandboxes`                                  |
| `/boxes/{boxId}`                      | `/sandboxes/{sandboxId}`                      |
| `/boxes/{boxId}/stop`                 | `/sandboxes/{sandboxId}/stop`                 |
| `/boxes/{boxId}/resume`               | `/sandboxes/{sandboxId}/resume`               |
| `/boxes/{boxId}/fork`                 | `/sandboxes/{sandboxId}/fork`                 |
| `/boxes/{boxId}/prompt`               | `/sandboxes/{sandboxId}/prompt`               |
| `/boxes/{boxId}/events`               | `/sandboxes/{sandboxId}/events`               |
| `/boxes/{boxId}/conversations`        | `/sandboxes/{sandboxId}/conversations`        |
| `/boxes/{boxId}/prompts/{promptId}`   | `/sandboxes/{sandboxId}/prompts/{promptId}`   |
| `/boxes/{boxId}/files`                | `/sandboxes/{sandboxId}/files`                |
| `/boxes/{boxId}/commands`             | `/sandboxes/{sandboxId}/commands`             |
| `/boxes/{boxId}/commands/{processId}` | `/sandboxes/{sandboxId}/commands/{processId}` |
| `/boxes/{boxId}/artifacts`            | `/sandboxes/{sandboxId}/artifacts`            |
| `/boxes/{boxId}/steer`                | `/sandboxes/{sandboxId}/steer`                |
| `/boxes/{boxId}/interrupt`            | `/sandboxes/{sandboxId}/interrupt`            |
| `/boxes/{boxId}/desktop`              | `/sandboxes/{sandboxId}/desktop`              |
| `/boxes/{boxId}/host`                 | `/sandboxes/{sandboxId}/host`                 |
| `/boxes/{boxId}/sshkey`               | `/sandboxes/{sandboxId}/sshkey`               |
| `/boxes/{boxId}/snapshots`            | `/sandboxes/{sandboxId}/snapshots`            |
| `/boxes/{boxId}/snapshots/latest`     | `/sandboxes/{sandboxId}/snapshots/latest`     |
| `/boxes/{boxId}/usage`                | `/sandboxes/{sandboxId}/usage`                |

**JSON keys (requests and responses)**

| Box                  | Boat                     |
| -------------------- | ------------------------ |
| `activeBoxes`        | `activeSandboxes`        |
| `box`                | `sandbox`                |
| `boxCount`           | `sandboxCount`           |
| `boxId`              | `sandboxId`              |
| `boxIds`             | `sandboxIds`             |
| `boxLifecycle`       | `sandboxLifecycle`       |
| `boxPlanDollars`     | `sandboxPlanDollars`     |
| `boxPlanKey`         | `sandboxPlanKey`         |
| `boxType`            | `sandboxType`            |
| `boxes`              | `sandboxes`              |
| `maxActiveBoxes`     | `maxActiveSandboxes`     |
| `passBoxCredentials` | `passSandboxCredentials` |
| `queuedBoxes`        | `queuedSandboxes`        |
| `sourceBoxId`        | `sourceSandboxId`        |

**OpenAPI schema / SDK type names**

| Box                             | Boat                                |
| ------------------------------- | ----------------------------------- |
| `Box`                           | `Sandbox`                           |
| `BoxActionResponse`             | `SandboxActionResponse`             |
| `BoxBearerAuth`                 | `BoatBearerAuth`                    |
| `BoxEnvironment`                | `SandboxEnvironment`                |
| `BoxEnvironmentListResponse`    | `SandboxEnvironmentListResponse`    |
| `BoxEnvironmentResponse`        | `SandboxEnvironmentResponse`        |
| `BoxEnvironmentVersionSummary`  | `SandboxEnvironmentVersionSummary`  |
| `BoxEvent`                      | `SandboxEvent`                      |
| `BoxId`                         | `SandboxId`                         |
| `BoxInfoResponse`               | `SandboxInfoResponse`               |
| `BoxListResponse`               | `SandboxListResponse`               |
| `BoxUsageResponse`              | `SandboxUsageResponse`              |
| `CreateBoxEnvironmentRequest`   | `CreateSandboxEnvironmentRequest`   |
| `CreateBoxRequest`              | `CreateSandboxRequest`              |
| `CreateBoxResponse`             | `CreateSandboxResponse`             |
| `UpdateBoxEnvironmentRequest`   | `UpdateSandboxEnvironmentRequest`   |
| `UpdateBoxRequest`              | `UpdateSandboxRequest`              |
| `UpgradeBoxEnvironmentRequest`  | `UpgradeSandboxEnvironmentRequest`  |
| `UpgradeBoxEnvironmentResponse` | `UpgradeSandboxEnvironmentResponse` |

**OpenAPI operation ids / SDK method names**

| Box                        | Boat                           |
| -------------------------- | ------------------------------ |
| `boxes`                    | `sandboxes`                    |
| `deleteBox`                | `deleteSandbox`                |
| `deliverBoxLifecycleEvent` | `deliverSandboxLifecycleEvent` |
| `getLatestBoxSnapshot`     | `getLatestSandboxSnapshot`     |
| `listBoxSnapshots`         | `listSandboxSnapshots`         |

**Envelope `type` values**

| Box            | Boat               |
| -------------- | ------------------ |
| `box.create`   | `sandbox.create`   |
| `box.created`  | `sandbox.created`  |
| `box.deleting` | `sandbox.deleting` |
| `box.error`    | `sandbox.error`    |
| `box.fork`     | `sandbox.fork`     |
| `box.forking`  | `sandbox.forking`  |
| `box.info`     | `sandbox.info`     |
| `box.list`     | `sandbox.list`     |
| `box.resume`   | `sandbox.resume`   |
| `box.resuming` | `sandbox.resuming` |
| `box.stopping` | `sandbox.stopping` |
| `box.updated`  | `sandbox.updated`  |
| `box.usage`    | `sandbox.usage`    |

**Error `code` values**

| Box                             | Boat                                |
| ------------------------------- | ----------------------------------- |
| `box_billing_not_configured`    | `sandbox_billing_not_configured`    |
| `box_busy`                      | `sandbox_busy`                      |
| `box_deletion_conflict`         | `sandbox_deletion_conflict`         |
| `box_direct_failed`             | `sandbox_direct_failed`             |
| `box_email_auth_not_configured` | `sandbox_email_auth_not_configured` |
| `box_not_archivable`            | `sandbox_not_archivable`            |
| `box_not_found`                 | `sandbox_not_found`                 |
| `box_not_promptable`            | `sandbox_not_promptable`            |
| `box_not_snapshotable`          | `sandbox_not_snapshotable`          |
| `box_purge_pending`             | `sandbox_purge_pending`             |
| `box_recent_snapshot_required`  | `sandbox_recent_snapshot_required`  |
| `box_required`                  | `sandbox_required`                  |
| `box_restoring`                 | `sandbox_restoring`                 |
| `box_resuming`                  | `sandbox_resuming`                  |
| `box_securing`                  | `sandbox_securing`                  |
| `box_starting`                  | `sandbox_starting`                  |
| `box_stopping`                  | `sandbox_stopping`                  |

**Webhook events**

| Box            | Boat               |
| -------------- | ------------------ |
| `box.archived` | `sandbox.archived` |
| `box.error`    | `sandbox.error`    |
| `box.hydrated` | `sandbox.hydrated` |
| `box.ready`    | `sandbox.ready`    |

**CLI environment variables**

| Box                         | Boat                         |
| --------------------------- | ---------------------------- |
| `BOX_AMSTERDAM_API_URL`     | `BOAT_AMSTERDAM_API_URL`     |
| `BOX_AMSTERDAM_CURRENT_ID`  | `BOAT_AMSTERDAM_CURRENT_ID`  |
| `BOX_API_URL`               | `BOAT_API_URL`               |
| `BOX_CURRENT_CONVO`         | `BOAT_CURRENT_CONVO`         |
| `BOX_CURRENT_CONVO_FILE`    | `BOAT_CURRENT_CONVO_FILE`    |
| `BOX_CURRENT_ID`            | `BOAT_CURRENT_ID`            |
| `BOX_CURRENT_ID_FILE`       | `BOAT_CURRENT_ID_FILE`       |
| `BOX_DASHBOARD_URL`         | `BOAT_DASHBOARD_URL`         |
| `BOX_DEV_API_URL`           | `BOAT_DEV_API_URL`           |
| `BOX_DEV_CURRENT_CONVO`     | `BOAT_DEV_CURRENT_CONVO`     |
| `BOX_DEV_CURRENT_ID`        | `BOAT_DEV_CURRENT_ID`        |
| `BOX_ID`                    | `BOAT_ID`                    |
| `BOX_ORG`                   | `BOAT_ORG`                   |
| `BOX_SCP_ARCHIVE`           | `BOAT_SCP_ARCHIVE`           |
| `BOX_SCP_LEGACY`            | `BOAT_SCP_LEGACY`            |
| `BOX_SCP_RSYNC`             | `BOAT_SCP_RSYNC`             |
| `BOX_SSH_TRACE`             | `BOAT_SSH_TRACE`             |
| `BOX_STAGING_API_URL`       | `BOAT_STAGING_API_URL`       |
| `BOX_STAGING_CURRENT_CONVO` | `BOAT_STAGING_CURRENT_CONVO` |
| `BOX_STAGING_CURRENT_ID`    | `BOAT_STAGING_CURRENT_ID`    |

**In-sandbox environment variables** (both spellings are exported inside every sandbox)

| Box                  | Boat                  |
| -------------------- | --------------------- |
| `BOX_ID`             | `BOAT_ID`             |
| `BOX_CURRENT_ID`     | `BOAT_CURRENT_ID`     |
| `BOX_DEV_CURRENT_ID` | `BOAT_DEV_CURRENT_ID` |
| `BOX_CLI_API_URL`    | `BOAT_CLI_API_URL`    |
| `BOX_CLI_CHANNEL`    | `BOAT_CLI_CHANNEL`    |
| `BOX_CLI_MODE`       | `BOAT_CLI_MODE`       |

**HTTP headers and query parameters**

| Box                                          | Boat               |
| -------------------------------------------- | ------------------ |
| `X-Box-Org`                                  | `X-Boat-Org`       |
| `?box_api_url=` (dashboard links)            | `?boat_api_url=`   |
| `?box_bootstrap=` (post-login links)         | `?boat_bootstrap=` |
| `?box_token=` (deprecated before the rename) | `?boat_token=`     |
| `?tab=boxes` (dashboard)                     | `?tab=sandboxes`   |

**CLI flags**

| Box                              | Boat                                 |
| -------------------------------- | ------------------------------------ |
| `boat api-key create --box <id>` | `boat api-key create --sandbox <id>` |

**Files and directories**

| Box                                   | Boat                                   |
| ------------------------------------- | -------------------------------------- |
| `.boxignore`                          | `.boatignore`                          |
| `~/.config/ascii/box/config.json`     | `~/.config/ascii/boat/config.json`     |
| `~/.config/ascii/box-dev/config.json` | `~/.config/ascii/boat-dev/config.json` |
| `~/.ascii/bin/box`                    | `~/.ascii/bin/boat`                    |
| agent skill `skills/box/SKILL.md`     | `skills/boat/SKILL.md`                 |

## Retirement policy

The current implementation preserves legacy API routes, binary and environment aliases, and hosted addresses. The October 31 header does not implement a `410 Gone`, disable installed clients, or remove DNS. The scope and timing of any future retirement still need an explicit policy decision; this guide does not promise either a shutdown on that date or permanent support.

Questions: [support@ascii.dev](mailto:support@ascii.dev).