> ## 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.

# Migration steps

> What to change to move from Box to Boat: the CLI, the SDKs, raw HTTP, webhooks, hosted URLs and the inside of a sandbox.

Do the steps that apply to you. For the full list of renamed names, read [Every renamed name](/migrating-from-box/renamed-names).

## 1. CLI

Install the `boat` CLI:

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

You stay signed in. `boat` reads the config that `box` wrote. Then do these steps:

1. In scripts and CI, replace `box` with `boat`. Subcommands do not change: `boat new`, `boat list`, `boat ssh`.
2. Rename `BOX_*` variables to `BOAT_*`. Now, if a `BOAT_*` variable is not set, Boat uses its `BOX_*` twin. It then prints a one-line notice on stderr.
3. Rename `.boxignore` files to `.boatignore`. Boat reads both files now. If a directory has both, `.boatignore` wins.
4. Change `boat api-key create --box bx_1` to `--sandbox bx_1`.

The final compatibility release of `box` prints a migration reminder. Use `boat` to get later updates. No date check disables legacy binaries.

## 2. SDKs

Replace the package:

<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 change your code:

| What | Box | Boat |
| - | - | - |
| Import | `ascii_box_sdk`, `@asciidev/box-sdk` | `boat_sdk`, `@boatdev/sdk` |
| Base URL | `https://ascii.dev/api/box/v1` | `https://boat.dev/api/v1` |
| Client class (keeps the product name) | `BoxApi` (`ascii_box_sdk.api.box_api`) | `BoatApi` (`boat_sdk.api.boat_api`) |
| Request and response types (say sandbox) | `CreateBoxRequest`, `Box`, `boxId`, `.box`, `.boxes`, `deleteBox` | `CreateSandboxRequest`, `Sandbox`, `sandboxId`, `.sandbox`, `.sandboxes`, `deleteSandbox` |

The helpers keep their names:

| SDK | Helpers |
| - | - |
| 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`, `stream_command` |
| TypeScript | `waitUntilReady`, `waitUntilIdle`, `waitForDesktop`, `waitForPrompt`, `waitForPromptDone`, `streamEvents`, `streamPrompt`, `stopAndRemove`, `readText`, `writeText`, `execCommand`, `streamCommand` |

In Python, pass the request body by keyword: `boat.create(create_sandbox_request=CreateSandboxRequest(...))`. See [Python SDK](/sdks/python).

To change the types and keys, do a whole-word search and replace:

| Find | Replace with |
| - | - |
| `box` | `sandbox` |
| `Box` | `Sandbox` |
| `boxes` | `sandboxes` |
| `Boxes` | `Sandboxes` |

Then make two changes by hand: the package import, and `BoxApi` to `BoatApi`.

## 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 use the new words: `sandbox` / `sandboxes` / `sandboxId`, `type: "sandbox.created"`, `code: "sandbox_not_found"`. Request bodies also use the new keys, for example `passSandboxCredentials` and `sourceSandboxId`.

A request to `/api/box/*` answers in box words now. It has these headers:

```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, search the logs for `Sunset`. Each match is a call that you did not move yet.

## 4. Webhooks

Webhooks that you created before the rename still send `box.*` events with payloads that say `box`. Signatures, headers and retries do not change.

To move a webhook:

1. Create it again through the Boat API, or with `boat webhook create`.
2. Delete the old webhook.

The new webhook sends `sandbox.*` events and `X-Ascii-Event: sandbox.ready`. There are 6 events: `ready`, `error`, `archived` (stopped), `hydrated`, `degraded` and `recovered`.

## 5. Hosted URLs

Each hosted route answers on two addresses, with the same `_token`:

* `https://<label>.on.ascii.dev`
* `https://<label>.on.boat.dev`

Update the links that you published or embedded to the `on.boat.dev` form. Boat has not decided the retirement policy for the `on.ascii.dev` form.

## 6. Inside a sandbox

* The `boat` CLI is on the PATH of each sandbox. `box` still points to it.
* Boat exports `BOAT_ID`, `BOAT_CURRENT_ID` and `BOAT_CLI_*` next to their `BOX_*` twins.
* Agent skills use the `boat` skill. Boat removes a `box` skill directory at the next start.


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