Quickstart - ascii

Install the CLI

curl -fsSL https://box.ascii.dev/install | sh

irm https://box.ascii.dev/install.ps1 | iex

curl -fsSL https://box.ascii.dev/install | sh

Onboarding starts automatically after installation and is short:

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.
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 so none of your credentials reach those Boxes. You can change it later.
Choose a Box plan in Stripe Checkout. It includes a free-of-charge 7-day trial.
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. GitHub, Google and an emailed 6-digit code are three ways in, on both the CLI and the dashboard. None of them is the “real” one: pick whichever you like, and you can add the others later.

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

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.

Signing in with Google or email does not give Box any access to your code. Cloning 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:

box new

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}'

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);

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)

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.

API guide

Learn auth, response envelopes, errors, lifecycle loops, agent prompts, desktop links, and OpenAPI reference usage.

SDKs

Typed Python and TypeScript/JavaScript clients for the Box API.

OpenAPI reference

Explore generated endpoint docs for creating, prompting, observing, stopping, resuming, and forking boxes.

Use in Code

Script the CLI with JSON output when a shell integration is the fastest path.

For API keys, app credentials, .env files, and other runtime secrets, configure Dashboard > Environment before running setup scripts in a Box. For a long uninterrupted workflow, disable auto-stop when creating the Box:

box new --no-auto-stop

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

await box.create({ createBoxRequest: { ttlSeconds: null } });

box.create(CreateBoxRequest(ttl_seconds=None))

See 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, TypeScript)	typed calls from your own service	`BOX_API_KEY`
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, team membership and invites, sign-in connections, per-box metrics, closing 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 and turning on zero 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

Machine Capabilities

See the runtimes, tools, desktop, and machine specs included in each Box.

Environments

Choose the repositories, secrets, and credentials every new Box starts with.

Setup & Scripts

Run setup scripts and pre-commit hooks, or drive setup from your own code.

Long-Running Tasks

Keep a Box running longer and restart runtime processes after resume or fork.

SSH Access

Connect to a Box over SSH from your terminal or external tools.

Desktop Streaming

Open the Box desktop and use Lux for browser or GUI automation.

Hosting

Expose a service running inside a Box on a public HTTPS URL.

SDKs

Use the typed Python and TypeScript/JavaScript clients for the Box API.

​Install the CLI

​Sign-in methods

​Create your first box

​Programmatic use

API guide

SDKs

OpenAPI reference

Use in Code

​Four ways to drive Box

​Next steps

Machine Capabilities

Environments

Setup & Scripts

Long-Running Tasks

SSH Access

Desktop Streaming

Hosting

SDKs

Install the CLI

Sign-in methods

Create your first box

Programmatic use

Four ways to drive Box

Next steps