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

# Quickstart

> Install Box, finish onboarding, and start your first cloud sandbox.

## Install the CLI

<CodeGroup>
  ```bash macOS theme={null}
  curl -fsSL https://box.ascii.dev/install | sh
  ```

  ```powershell Windows theme={null}
  irm https://box.ascii.dev/install.ps1 | iex
  ```

  ```bash Linux theme={null}
  curl -fsSL https://box.ascii.dev/install | sh
  ```
</CodeGroup>

Onboarding starts automatically after installation and is short:

1. Sign in through your browser with GitHub, Google, or a code sent to your email. The CLI asks which one; `box onboard --google` and `box onboard --email you@example.com` answer it up front.
2. Say what the Boxes are for: your own work, or a platform of yours driven by third-party users. The second is the default, and it marks your environment [safe for third parties](/box/environments#safe-for-third-parties) so none of your credentials reach those Boxes. You can change it later.
3. Choose a Box plan in Stripe Checkout. It includes a free-of-charge 7-day trial.
4. Return to the terminal while the CLI waits for billing to become active.

Repositories are not asked for at this point. A Box is useful with none, and you add them whenever you like from [Environments](/box/environments).

### Reinstalling, or a second machine

Your plan, environment, boxes and settings live on your account, not on the machine. Reinstalling Box, or installing it on a new computer, only needs that machine signed in:

```bash theme={null}
box onboard   # or: box login
```

Sign in the same way you did the first time and `box onboard` picks up the account you already have: it skips every step that account has finished, and does **not** open Stripe Checkout when your plan is active.

<Note>
  Use the same sign-in method as before. A method that has never been connected to your account opens a **separate** one, with its own empty plan, which is the usual reason a reinstall looks like it is asking you to subscribe again. See [Sign-in methods](#sign-in-methods).
</Note>

### Sign-in methods

GitHub, Google and an emailed 6-digit code are three ways in, on both the CLI and the [dashboard](https://box.ascii.dev/box/dashboard). None of them is the "real" one: pick whichever you like, and you can add the others later.

```bash theme={null}
box login                          # asks: github, google, or email
box login --google
box login --email you@example.com
```

Each method you use is a **connection** on your account, listed under [Dashboard > Account](https://box.ascii.dev/box/dashboard?tab=account). They all open the same account, with the same boxes, settings and billing. Add or remove them at any time, as long as one remains. The connection marked **primary** decides which address receives account notifications, so making another one primary is how you change that address.

<Note>
  Signing in with a method that is not yet connected creates a **separate** account, even when the email address matches. To use a second method on an account you already have, sign in the way you always do and add the connection from the Account tab. Moving a connection between two existing accounts is a merge, which is support-side only.
</Note>

Signing in with Google or email does not give Box any access to your code. Cloning [repositories](/box/environments#repositories) needs a GitHub connection, which you can add whenever you first want one.

## Create your first box

Create a one-hour Box from whichever surface fits your workflow:

<CodeGroup>
  ```bash CLI theme={null}
  box new
  ```

  ```bash curl theme={null}
  curl -sS -X POST "https://ascii.dev/api/box/v1/boxes" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ttlSeconds":3600}'
  ```

  ```ts TypeScript theme={null}
  import { BoxApi, Configuration } from "@asciidev/box-sdk";

  const box = new BoxApi(new Configuration({
    basePath: "https://ascii.dev/api/box/v1",
    accessToken: process.env.BOX_API_KEY!,
  }));

  const created = await box.create({ createBoxRequest: { ttlSeconds: 3600 } });
  console.log(created.box.id);
  ```

  ```python Python theme={null}
  import os
  from ascii_box_sdk import ApiClient, Configuration
  from ascii_box_sdk.api.box_api import BoxApi
  from ascii_box_sdk.models.create_box_request import CreateBoxRequest

  config = Configuration(host="https://ascii.dev/api/box/v1", access_token=os.environ["BOX_API_KEY"])
  with ApiClient(config) as client:
      box = BoxApi(client)
      created = box.create(CreateBoxRequest(ttl_seconds=3600))
      print(created.box.id)
  ```
</CodeGroup>

In the CLI flow, follow the instructions printed.

## Programmatic use

Building Box into a product, CI system, hosted worker, or agent platform? Use the HTTP API or an SDK to create or resume a Box, prompt it, observe events, return a desktop or app preview URL, then stop, resume, fork, or delete the Box according to your product lifecycle.

<CardGroup cols={2}>
  <Card title="API guide" icon="brackets-curly" href="/box/api/v1">
    Learn auth, response envelopes, errors, lifecycle loops, agent prompts, desktop links, and OpenAPI reference usage.
  </Card>

  <Card title="SDKs" icon="cubes" href="/box/sdks/overview">
    Typed Python and TypeScript/JavaScript clients for the Box API.
  </Card>

  <Card title="OpenAPI reference" icon="book-open" href="/box/api/reference/boxes/create-box">
    Explore generated endpoint docs for creating, prompting, observing, stopping, resuming, and forking boxes.
  </Card>

  <Card title="Use in Code" icon="code" href="/box/use-in-code">
    Script the CLI with JSON output when a shell integration is the fastest path.
  </Card>

  <Card title="Agent sign-in" icon="robot" href="/box/agent-auth">
    Let an agent register itself, claim a human, and start the 7-day free trial via auth.md.
  </Card>
</CardGroup>

For API keys, app credentials, `.env` files, and other runtime secrets, configure [Dashboard > Environment](https://box.ascii.dev/box/dashboard?tab=environment) before running setup scripts in a Box.

For a long uninterrupted workflow, disable auto-stop when creating the Box:

<CodeGroup>
  ```bash CLI theme={null}
  box new --no-auto-stop
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOX_API_BASE/boxes" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ttlSeconds":null}'
  ```

  ```ts TypeScript theme={null}
  await box.create({ createBoxRequest: { ttlSeconds: null } });
  ```

  ```python Python theme={null}
  box.create(CreateBoxRequest(ttl_seconds=None))
  ```
</CodeGroup>

See [Long-Running Tasks](/box/long-running-tasks) for timed extension and resume/fork behavior.

## Four ways to drive Box

Everything below is the same platform behind four front doors. Code examples across these docs come as **CLI**, **curl**, **TypeScript** and **Python** tabs; pick your tab once and the rest of the page follows it.

|                                                                           | Use it for                                                   | Auth                             |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------- |
| **CLI** (`box`)                                                           | your terminal, CI jobs, shell scripts, and from inside a Box | browser sign-in or `BOX_API_KEY` |
| **REST API**                                                              | any language, webhooks, anything the SDKs do not cover yet   | `BOX_API_KEY`                    |
| **SDKs** ([Python](/box/sdks/python), [TypeScript](/box/sdks/typescript)) | typed calls from your own service                            | `BOX_API_KEY`                    |
| **[Dashboard](https://box.ascii.dev/box/dashboard)**                      | one-off work, and the things that must not be automatable    | browser sign-in                  |

They are not identical, and the differences are deliberate:

| Only in the dashboard                                                                                                                                                                                                                  | Only in the CLI                                            | Only in the API and SDKs                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Webhook delivery history](/box/webhooks), [organization membership and invites](/box/billing#organizations), [sign-in connections](#sign-in-methods), per-box metrics, [closing your account](/box/data-retention#close-your-account) | interactive SSH, SCP, port forwarding, `box snapshot pull` | editing a webhook in place (`PATCH /webhooks/{webhookId}`), reading and writing files in a Box without SSH |

Creating, rotating and revoking [API keys](/box/api-keys) and turning on [zero data retention](/box/data-retention) need a browser sign-in on either the CLI or the dashboard, and are refused to an API key on purpose.

## Next steps

<CardGroup cols={2}>
  <Card title="Machine Capabilities" icon="microchip" href="/box/machines">
    See the runtimes, tools, desktop, and machine specs included in each Box.
  </Card>

  <Card title="Environments" icon="key" href="/box/environments">
    Choose the repositories, secrets, and credentials every new Box starts with.
  </Card>

  <Card title="Setup & Scripts" icon="terminal" href="/box/setup">
    Run setup scripts, or drive setup from your own code.
  </Card>

  <Card title="Long-Running Tasks" icon="clock" href="/box/long-running-tasks">
    Keep a Box running longer and restart runtime processes after resume or fork.
  </Card>

  <Card title="SSH Access" icon="terminal" href="/box/ssh-access">
    Connect to a Box over SSH from your terminal or external tools.
  </Card>

  <Card title="Desktop Streaming" icon="desktop" href="/box/desktop-streaming">
    Open the Box desktop, and let the Box's agents drive it with the `computer` tools.
  </Card>

  <Card title="Hosting" icon="globe" href="/box/hosting">
    Expose a service running inside a Box on a public HTTPS URL.
  </Card>

  <Card title="SDKs" icon="cubes" href="/box/sdks/overview">
    Use the typed Python and TypeScript/JavaScript clients for the Box API.
  </Card>
</CardGroup>