> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.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 with GitHub in your browser.
2. Optionally choose repositories for Box to use. You can skip this and add repositories 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.

## 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>
</CardGroup>

For API keys, app credentials, `.env` files, and other runtime secrets, configure [Dashboard > Secrets](https://box.ascii.dev/box/dashboard?tab=secrets) 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.

## 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="Repositories" icon="github" href="/box/repositories">
    Choose which GitHub repositories Box clones into new VMs.
  </Card>

  <Card title="Secrets & Setup" icon="key" href="/box/secrets">
    Configure secrets, run setup scripts, and restart services after resume or fork.
  </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 use Lux for browser or GUI automation.
  </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>