Skip to main content

​
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:
  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: 
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 > Secrets 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.

​
Next steps

Machine Capabilities

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

Repositories

Choose which GitHub repositories Box clones into new VMs.

Secrets & Setup

Configure secrets, run setup scripts, and restart services after resume or fork.

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.