### Complete Example: Provision and Exercise Box Environment

Source: https://docs.ascii.dev/box/integrations/harbor

This Python script demonstrates provisioning a Box-backed environment, uploading a file, executing a command, and reading the output. It's useful for verifying your setup before integrating with larger Harbor runs. Ensure the BOX_API_KEY is set before running.

```python
import asyncio
import tempfile
from pathlib import Path

from harbor.models.task.config import EnvironmentConfig
from harbor.models.trial.paths import TrialPaths
from harbor_box_environment import BoxEnvironment


async def main() -> None:
    with tempfile.TemporaryDirectory() as raw:
        tmp = Path(raw)
        # Harbor requires an environment definition. Box runs its default image;
        # the Dockerfile's WORKDIR drives the agent's working directory.
        env_dir = tmp / "environment"
        env_dir.mkdir()
        (env_dir / "Dockerfile").write_text("FROM ubuntu:24.04\nWORKDIR /workspace\n")
        trial_paths = TrialPaths(tmp / "trial")
        trial_paths.mkdir()

        env = BoxEnvironment(
            environment_dir=env_dir,
            environment_name="harbor-hello",
            session_id="hello-session",
            trial_paths=trial_paths,
            task_env_config=EnvironmentConfig(workdir="/workspace"),
            ttl_seconds=600,  # auto-stop the Box after 10 min of inactivity
        )

        await env.start(force_build=False)  # provisions a Box and waits until ready
        try:
            # Write a file, run a command against it, and read the result back.
            await env.upload_file(__file__, "/workspace/hello_box.py")
            result = await env.exec(
                "echo 'hello from Box' > notes.txt && cat notes.txt && uname -a"
            )
            print("exit:", result.return_code)
            print(result.stdout)
        finally:
            await env.stop(delete=True)


if __name__ == "__main__":
    asyncio.run(main())

```

```bash
BOX_API_KEY=box_... python hello_box.py
```

--------------------------------

### Combine Shell Commands with Lux Automation

Source: https://docs.ascii.dev/box/desktop-streaming

This example demonstrates launching a browser with a shell command, focusing the window, and then starting and running a Lux automation session for UI interaction.

```bash
DISPLAY=:0 google-chrome-stable "https://example.com"
wmctrl -a "Chrome"
lux start "Complete the checkout flow in the open browser"
lux run
```

```bash
curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"DISPLAY=:0 google-chrome-stable \"https://example.com\" && wmctrl -a Chrome && lux start \"Complete the checkout flow in the open browser\" && lux run"}'
```

```typescript
await box.command({
    boxId: "bx_f7k2q9hd",
    commandRequest: {
      command: 'DISPLAY=:0 google-chrome-stable "https://example.com" && wmctrl -a Chrome && lux start "Complete the checkout flow in the open browser" && lux run',
    },
  });
```

```python
box.command("bx_f7k2q9hd", CommandRequest(
    command='DISPLAY=:0 google-chrome-stable "https://example.com" && wmctrl -a Chrome && lux start "Complete the checkout flow in the open browser" && lux run',
))
```

--------------------------------

### Install Box CLI

Source: https://docs.ascii.dev/box/cli-reference

Run this command once to install the Box CLI. It fetches the installation script and executes it.

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

--------------------------------

### Run Setup Script via Box CLI

Source: https://docs.ascii.dev/box/secrets

Use the Box CLI to get a Box ID and then execute a local setup script within the Box. This method streams stdin, stdout, and stderr.

```bash
box_id=$(box new --json | jq -r 'select(.event == "ready") | .id')
box ssh "$box_id" -- bash -s < ./setup.sh
```

--------------------------------

### Install Box CLI

Source: https://docs.ascii.dev/box/quickstart

Install the Box CLI for macOS, Windows, or Linux. Follow the on-screen instructions after installation to complete onboarding.

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

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

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

--------------------------------

### Execute Commands on a Box

Source: https://docs.ascii.dev/box/long-running-tasks

Execute setup scripts or start development servers on a Box using SSH or the command API. Ensure commands are idempotent for repeatable workflows.

```bash
box ssh "$box_id" -- bash -s < ./setup.sh
box ssh "$box_id" "cd /home/user/ariana-ide-private && npm run dev"
```

```bash
curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/commands" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"bash ./setup.sh","cwd":"ariana-ide-private"}'

curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/commands" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"npm run dev","cwd":"ariana-ide-private"}'
```

```typescript
await box.command({ boxId, commandRequest: { command: "bash ./setup.sh", cwd: "ariana-ide-private" } });
await box.command({ boxId, commandRequest: { command: "npm run dev", cwd: "ariana-ide-private" } });
```

```python
box.command(box_id, CommandRequest(command="bash ./setup.sh", cwd="ariana-ide-private"))
box.command(box_id, CommandRequest(command="npm run dev", cwd="ariana-ide-private"))
```

--------------------------------

### Install ASCII.dev CLI

Source: https://docs.ascii.dev/

Installs the ASCII.dev command-line interface. Run this command in your terminal.

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

```

--------------------------------

### Install Eve and Eve-Box Packages

Source: https://docs.ascii.dev/box/integrations/eve

Install the necessary npm packages for Eve and the @asciidev/eve-box backend. Ensure your TypeScript configuration is set to modern standards.

```bash
npm install @asciidev/eve-box eve
```

--------------------------------

### Run Setup Script via Box SDK (Python)

Source: https://docs.ascii.dev/box/secrets

Execute a setup script within the Box using the Box SDK for Python. This requires importing the CommandRequest model and specifying command details.

```python
from ascii_box_sdk.models.command_request import CommandRequest

box.command(
    box_id,
    CommandRequest(command="bash -lc './setup.sh'", cwd="ariana-ide-private", timeout_seconds=60),
)
```

--------------------------------

### Start hosting an application port

Source: https://docs.ascii.dev/box/hosting

Execute these commands to start hosting a specific port with a title. The `host` command makes your application accessible via a public URL. By default, the URL is protected with an access token.

```bash
host 3000 --title "App preview"
```

```bash
curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"host 3000 --title \"App preview\""}'
```

```typescript
await box.command({
    boxId: "bx_f7k2q9hd",
    commandRequest: { command: 'host 3000 --title "App preview"' },
  });
```

```python
box.command("bx_f7k2q9hd", CommandRequest(command='host 3000 --title "App preview"'))
```

--------------------------------

### Run Setup Script via Box SDK (TypeScript)

Source: https://docs.ascii.dev/box/secrets

Use the Box SDK for TypeScript to execute a setup script within the Box. This method allows specifying the command, working directory, and timeout.

```typescript
await box.command({
    boxId,
    commandRequest: {
      command: "bash -lc './setup.sh'",
      cwd: "ariana-ide-private",
      timeoutSeconds: 60,
    },
  });
```

--------------------------------

### Install Harbor Box Package

Source: https://docs.ascii.dev/box/integrations/harbor

Install the necessary package for the Harbor Box integration. This command also installs its dependencies, including Harbor itself and httpx.

```bash
pip install harbor-box
```

--------------------------------

### Example Request Body for Repo Selection

Source: https://docs.ascii.dev/box/api/reference/account/select-repository-for-boxes

This example demonstrates the structure of a request body to select a repository. It includes the required `repositoryId` and an optional `baseBranch`.

```json
{
  "repositoryId": "repo_org_123",
  "baseBranch": "dev"
}
```

--------------------------------

### Install Python Box SDK

Source: https://docs.ascii.dev/box/sdks/overview

Install the Python Box SDK using pip. This command installs the necessary package for Python development.

```bash
python -m pip install ascii-box-sdk
```

--------------------------------

### Run Setup Script via Box API (cURL)

Source: https://docs.ascii.dev/box/secrets

Execute a setup script within the Box using a cURL command to the Box API. Ensure the script is present in the Box's working directory.

```bash
curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/commands" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"bash -lc ./setup.sh","cwd":"ariana-ide-private","timeoutSeconds":60}'
```

--------------------------------

### Example Prompt Request: Repo Work

Source: https://docs.ascii.dev/box/api/reference/agent/prompt-box-agent

Example payload for queuing a 'repo work' task using the Codex provider. Specifies the model and reasoning effort.

```json
{
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium",
  "prompt": "> Work on the selected repo, run tests, fix failures, commit
    the result, and report any hosted preview URL."
}
```

--------------------------------

### Example Prompt Response: Queued

Source: https://docs.ascii.dev/box/api/reference/agent/prompt-box-agent

Example response indicating that a prompt has been successfully queued. Includes a unique ID for the prompt run and its initial status.

```json
{
  "ok": true,
  "type": "prompt.queued",
  "id": "bx_23456789",
  "promptId": "prompt_123",
  "promptRun": {
    "id": "prompt_123",
    "promptId": "prompt_123",
    "boxId": "bx_23456789",
    "status": "queued",
    "done": false
  },
  "status": "queued",
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium"
}
```

--------------------------------

### Snapshot Download Response Example

Source: https://docs.ascii.dev/box/api/reference/snapshots/get-snapshot-download

This example shows the structure of a successful response when requesting snapshot download URLs. It includes metadata about the snapshot, reconstruction instructions, and signed URLs for the inventory and chunks.

```yaml
openapi: 3.1.0
info:
  title: Box Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    Box sandboxes from backend services, CI jobs, hosted workers, and Box
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://ascii.dev/api/box/v1
security:
  - BoxBearerAuth: []
tags:
  - name: Box
    description: >-
      Unified Box account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /snapshots/{snapshotId}/download:
    get:
      tags:
        - Box
      summary: Get snapshot download
      description: >
        Return time-limited signed URLs for every chunk needed to reconstruct
        the box filesystem at this snapshot (the full chain, base through this
        generation), plus the inventory. Download the chunks and reassemble them
        as described by `reconstruct`. The `box snapshot pull` CLI command does
        this for you.
      operationId: getSnapshotDownload
      parameters:
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Signed chunk URLs for the snapshot chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotDownloadResponse'
              examples:
                download:
                  value:
                    ok: true
                    type: snapshot.download
                    snapshotId: 7417be09-d419-4ae0-b3fc-7f04a5a71ef1
                    boxId: bx_23456789
                    kind: incremental
                    generation: 3
                    expiresInSeconds: 3600
                    reconstruct: >-
                      Download every chunk. For each snapshot in ascending
                      generation, concat its chunks by chunkIndex and pipe
                      through `zstd -d | tar -x`.
                    inventory:
                      r2Key: chains/4ced5b04/inventory-3.json.zst
                      signedUrl: >-
                        https://r2.example/chains/4ced5b04/inventory-3.json.zst?sig=redacted
                    chunks:
                      - snapshotId: 2db50582-716c-424c-817e-9495484f88dd
                        generation: 0
                        chunkIndex: 0
                        r2Key: chains/4ced5b04/snapshots/2db50582/chunks/00.tar.zst
                        sizeBytes: 209715200
                        sha256: >-
                          9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                        signedUrl: >-
                          https://r2.example/chains/4ced5b04/snapshots/2db50582/chunks/00.tar.zst?sig=redacted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SnapshotId:
      name: snapshotId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Snapshot id returned by the snapshot list/latest calls.
  schemas:
    SnapshotDownloadResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - snapshotId
            - boxId
            - kind
            - generation
            - expiresInSeconds
            - reconstruct
            - chunks
          properties:
            type:
              type: string
              const: snapshot.download
            snapshotId:
              type: string
              format: uuid
            boxId:
              type: string
            kind:
              type: string
              enum:
                - base
                - incremental
                - legacy
            generation:
              type: integer
            expiresInSeconds:
              type: integer
              description: Lifetime of every `signedUrl` in this response.
            reconstruct:
              type: string
              description: >-
                Human-readable note on how to reassemble the chunks into a
                filesystem.
            inventory:
              oneOf:
                - type: object
                  required:

```

--------------------------------

### Execute Setup Script via SSH (Bash)

Source: https://docs.ascii.dev/box/use-in-code

Executes a local setup script within a remote Box instance using `box ssh`. Stdin is piped to the remote bash process.

```bash
box ssh "$box_id" -- bash -s < ./setup.sh
```

--------------------------------

### Example Response Body for Successful Repo Selection

Source: https://docs.ascii.dev/box/api/reference/account/select-repository-for-boxes

This example shows a successful response when a repository is selected or updated. It confirms the operation's success and details the selected repository.

```json
{
  "ok": true,
  "type": "repos.updated",
  "success": true,
  "environmentId": "env_123",
  "selectedRepositories": [
    {
      "databaseId": "repo_org_123456",
      "name": "web",
      "fullName": "acme/web",
      "baseBranch": "dev",
      "setupRoutineId": null,
      "setupScript": "",
      "setupBlocking": false,
      "preCommitHooks": []
    }
  ]
}
```

--------------------------------

### Example Box Events Response (Progress)

Source: https://docs.ascii.dev/box/api/reference/agent/list-box-events

This example shows a typical JSON response for listing box events, specifically demonstrating progress-related events. It includes prompt, tool usage, and response events.

```json
{
  "ok": true,
  "type": "events.list",
  "id": "bx_23456789",
  "events": [
    {
      "id": "prompt_123",
      "type": "prompt",
      "timestamp": 1780347055370,
      "taskId": "prompt_123",
      "data": {
        "prompt": "Run tests and summarize failures.",
        "status": "running",
        "is_reverted": false
      }
    },
    {
      "id": "response_123-tools",
      "type": "response",
      "timestamp": 1780347063427,
      "taskId": "prompt_123",
      "data": {
        "content": "",
        "model": "gpt-5.4",
        "tools": [
          {
            "use": {
              "id": "call_123",
              "type": "tool_use",
              "name": "Bash",
              "input": {
                "command": "npm test"
              }
            },
            "result": {
              "type": "tool_result",
              "tool_use_id": "call_123",
              "is_error": false,
              "content": "{\"exitCode\":0}"
            }
          }
        ],
        "is_reverted": false
      }
    },
    {
      "id": "response_123",
      "type": "response",
      "timestamp": 1780347065650,
      "taskId": "prompt_123",
      "data": {
        "content": "Tests passed.",
        "model": "gpt-5.4",
        "is_reverted": false
      }
    }
  ],
  "pageInfo": {
    "nextCursor": null,
    "hasMore": false,
    "limit": 100
  }
}
```

--------------------------------

### Railway Start Command with Box Login

Source: https://docs.ascii.dev/box/use-in-production

Combines Box CLI login with starting an application on Railway. Ensures the application starts only after successful authentication.

```bash
box login "$BOX_API_KEY" --json && npm start
```

--------------------------------

### Example Prompt Request: Computer Use

Source: https://docs.ascii.dev/box/api/reference/agent/prompt-box-agent

Example payload for queuing a 'computer use' task using the Claude Code provider. Specifies a higher reasoning effort.

```json
{
  "provider": "claude-code",
  "model": "sonnet",
  "reasoningEffort": "high",
  "prompt": "> Use the browser to research flight options to France and
    return the best itinerary summary with source links."
}
```

--------------------------------

### Install Box CLI in Debian/Ubuntu Docker Image

Source: https://docs.ascii.dev/box/use-in-production

Installs the Box CLI and OpenSSH client in a Debian-based Docker image. Authenticates at runtime by downloading the CLI and configuring it.

```dockerfile
FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        openssh-client \
    && rm -rf /var/lib/apt/lists/*

RUN set -eux; \
    arch=\"$(uname -m)\"; \
    case "$arch" in \
        x86_64|amd64) box_arch=\"x64\" ;; \
        arm64|aarch64) box_arch=\"arm64\" ;; \
        *) echo \"Unsupported arch: $arch\" >&2; exit 1 ;; \
    esac; \
    curl -fsSL \"https://ascii.dev/api/box/cli/download?platform=linux-${box_arch}&channel=ascii-prod\" \
        -o /usr/local/bin/box; \
    chmod +x /usr/local/bin/box; \
    mkdir -p /root/.config/ascii/box; \
    printf '{\
  \"api_url\": \"https://ascii.dev\",\
  \"channel\": \"ascii-prod\"\
}\
' \
        > /root/.config/ascii/box/config.json
```

--------------------------------

### Install Box CLI in Alpine Docker Image

Source: https://docs.ascii.dev/box/use-in-production

Installs the Box CLI and OpenSSH client in an Alpine Linux Docker image. Authenticates at runtime by downloading the CLI and configuring it.

```dockerfile
FROM alpine:3.20

RUN apk add --no-cache ca-certificates curl openssh-client

RUN set -eux; \
    arch=\"$(uname -m)\"; \
    case "$arch" in \
        x86_64|amd64) box_arch=\"x64\" ;; \
        arm64|aarch64) box_arch=\"arm64\" ;; \
        *) echo \"Unsupported arch: $arch\" >&2; exit 1 ;; \
    esac; \
    curl -fsSL \"https://ascii.dev/api/box/cli/download?platform=linux-${box_arch}&channel=ascii-prod\" \
        -o /usr/local/bin/box; \
    chmod +x /usr/local/bin/box; \
    mkdir -p /root/.config/ascii/box; \
    printf '{\
  \"api_url\": \"https://ascii.dev\",\
  \"channel\": \"ascii-prod\"\
}\
' \
        > /root/.config/ascii/box/config.json
```

--------------------------------

### Desktop Streaming URL - Provisioning State

Source: https://docs.ascii.dev/box/api/reference/agent/get-desktop-streaming-url

Example response when the desktop streaming URL is still being provisioned. You should poll again.

```json
{
  "ok": true,
  "type": "desktop.provisioning",
  "provisioning": true,
  "message": "Preparing VNC desktop…"
}
```

--------------------------------

### OpenAPI Specification for Get Box

Source: https://docs.ascii.dev/box/api/reference/boxes/get-box

This OpenAPI specification defines the GET /boxes/{boxId} endpoint for retrieving Box details. It includes request parameters, response schemas, and example responses.

```yaml
openapi: 3.1.0
info:
  title: Box Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    Box sandboxes from backend services, CI jobs, hosted workers, and Box
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://ascii.dev/api/box/v1
security:
  - BoxBearerAuth: []
tags:
  - name: Box
    description: >-
      Unified Box account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /boxes/{boxId}:
    parameters:
      - $ref: '#/components/parameters/BoxId'
    get:
      tags:
        - Box
      summary: Get box
      description: Poll this endpoint after create, stop, resume, or fork operations.
      operationId: get
      responses:
        '200':
          description: Box details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoxInfoResponse'
              examples:
                box:
                  value:
                    ok: true
                    type: box.info
                    box:
                      id: bx_23456789
                      name: Box 2026-05-31 12:00
                      state: idle
                      url: https://machine.on.ascii.dev
                      ip: 203.0.113.10
                      createdAt: '2026-05-31T12:00:00Z'
                      updatedAt: '2026-05-31T12:05:00Z'
                      archiveAfter: '2026-05-31T13:00:00Z'
                      desktopAvailable: true
                      desktopUrl: https://desktop.example/stream.html?token=redacted
                      snapshotAvailable: false
                      snapshotCompletedAt: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    BoxId:
      name: boxId
      in: path
      required: true
      schema:
        type: string
        pattern: '^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$'
      description: Public Box id returned by create/list/get box calls.
  schemas:
    BoxInfoResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - box
          properties:
            type:
              type: string
              examples:
                - box.info
            box:
              $ref: '#/components/schemas/Box'
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    Box:
      type: object
      required:
        - id
        - name
        - state
        - desktopAvailable
        - snapshotAvailable
      properties:
        id:
          type: string
          pattern: '^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$'
          examples:
            - bx_23456789
        name:
          type: string
          examples:
            - Box 2026-05-31 12:00
        state:
          type: string
          enum:
            - init
            - provisioning
            - provisioned
            - cloning
            - ready
            - idle
            - running
            - archiving
            - archived
            - error
        url:
          type:
            - string
            - 'null'
          format: uri
          description: Machine URL when assigned.
        ip:
          type:
            - string
            - 'null'
          description: Machine IPv4 address when assigned.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
        archiveAfter:
          type:
            - string
            - 'null'
          format: date-time
          description: Automatic archival time, or null when auto-stop is disabled.
        desktopAvailable:
          type: boolean
        desktopUrl:
          type:
            - string
            - 'null'
          format: uri
          description: Secret-bearing desktop stream URL when available. Redact from logs.
        snapshotAvailable:
          type: boolean
        snapshotCompletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-

```

--------------------------------

### Get Box Secrets Setup

Source: https://docs.ascii.dev/box/api/reference/account/get-box-secrets-setup

Returns the environment variables and secret files configured for Boxes.

```APIDOC
## GET /secrets

### Description
Returns the environment variables and secret files configured for Boxes.

### Method
GET

### Endpoint
/secrets

### Parameters

### Request Body

### Request Example

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **type** (string) - Stable success envelope discriminator.
- **environmentId** (string) - The ID of the environment.
- **envContents** (string) - The contents of the environment variables.
- **secretFiles** (array) - An array of secret files.
  - **path** (string) - The path of the secret file.
  - **contents** (string) - The contents of the secret file.

#### Response Example
```json
{
  "ok": true,
  "type": "secrets.info",
  "environmentId": "env_123",
  "envContents": "OPENAI_API_KEY=sk-...",
  "secretFiles": [
    {
      "path": ".config/service-account.json",
      "contents": "{\"type\": \"service_account\"}"
    }
  ]
}
```

#### Error Response (401)
- **description**: Missing or invalid bearer token.
```

--------------------------------

### Get Box Secrets Setup

Source: https://docs.ascii.dev/box/api/reference/account/get-box-secrets-setup

Returns the environment variables and secret files configured for Boxes.

```APIDOC
## Get Box Secrets Setup

### Description
Returns the environment variables and secret files configured for Boxes.

### Method
GET

### Endpoint
/account/get-box-secrets-setup
```

--------------------------------

### Create, Prompt, and Clean Up a Box

Source: https://docs.ascii.dev/box/sdks/python

Example demonstrating the lifecycle of a box: creation, updating, waiting for readiness, prompting, waiting for a prompt response, retrieving events, and finally stopping the box. Handles potential provider configuration errors.

```python
import os
import time

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
from ascii_box_sdk.models.prompt_request import PromptRequest
from ascii_box_sdk.models.update_box_request import UpdateBoxRequest
from ascii_box_sdk import wait_until_ready, wait_for_prompt

config = Configuration(
    host=os.getenv("BOX_BASE_URL", "https://ascii.dev/api/box/v1"),
    access_token=os.environ["BOX_API_KEY"],
)

box_id = None
with ApiClient(config) as client:
    box = BoxApi(client)

    try:
        created = box.create(CreateBoxRequest(ttl_seconds=1800))
        box_id = created.box.id

        box.update(box_id, UpdateBoxRequest(name="sdk-demo"))

        wait_until_ready(box, box_id)

        queued = box.prompt(
            box_id,
            PromptRequest(
                provider="codex",
                prompt="Inspect the repository and summarize the test command.",
            ),
        )

        run = wait_for_prompt(box, box_id, queued.prompt_id)
        print(run.status)

        events = box.events(box_id, limit=50, type="prompt,response,git_checkpoint")
        print(events.events)
    finally:
        if box_id:
            box.stop(box_id)
```

--------------------------------

### OpenAPI Specification for Get Current Box User

Source: https://docs.ascii.dev/box/api/reference/account/get-current-box-user

This OpenAPI 3.1.0 specification defines the GET /me endpoint for the Box Public API v1. It outlines the request, responses, and schemas, including an example of the user response.

```yaml
openapi: 3.1.0
info:
  title: Box Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    Box sandboxes from backend services, CI jobs, hosted workers, and Box
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://ascii.dev/api/box/v1
security:
  - BoxBearerAuth: []
tags:
  - name: Box
    description: >-
      Unified Box account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /me:
    get:
      tags:
        - Box
      summary: Get current Box user
      description: Returns GitHub identity for the authenticated Box account.
      operationId: me
      responses:
        '200':
          description: Current user information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
              examples:
                user:
                  value:
                    ok: true
                    type: user.info
                    user:
                      login: octocat
                      email: octocat@example.com
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    MeResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - user
          properties:
            type:
              type: string
              const: user.info
            user:
              type: object
              properties:
                login:
                  type: string
                email:
                  type:
                    - string
                    - 'null'
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - box.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: box.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
  securitySchemes:
    BoxBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: box_api_key
      description: >-
        Box bearer token in the form `box_...`. Service API keys authenticate
        Box operations.

```

--------------------------------

### OpenAPI Specification for Get Snapshot Tree

Source: https://docs.ascii.dev/box/api/reference/snapshots/get-snapshot-tree

This OpenAPI 3.1 specification defines the GET /snapshots/{snapshotId}/tree endpoint for the Box Public API v1. It details the request parameters, response structure, and example payloads for retrieving snapshot file tree information.

```yaml
openapi: 3.1.0
info:
  title: Box Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    Box sandboxes from backend services, CI jobs, hosted workers, and Box
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://ascii.dev/api/box/v1
security:
  - BoxBearerAuth: []
tags:
  - name: Box
    description: >-
      Unified Box account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /snapshots/{snapshotId}/tree:
    get:
      tags:
        - Box
      summary: Get snapshot file tree
      description: >-
        List the files and folders captured in a snapshot, with sizes. Returns a
        flat list of entries you can render as a tree.
      operationId: getSnapshotTree
      parameters:
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Flat file/folder listing for the snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotTreeResponse'
              examples:
                tree:
                  value:
                    ok: true
                    type: snapshot.tree
                    snapshotId: 7417be09-d419-4ae0-b3fc-7f04a5a71ef1
                    boxId: bx_23456789
                    generation: 3
                    treeAvailable: true
                    truncated: false
                    fileCount: 6781
                    totalSizeBytes: 458291
                    entries:
                      - path: src
                        kind: dir
                      - path: src/main.ts
                        kind: file
                        size: 1024
                legacy:
                  value:
                    ok: true
                    type: snapshot.tree
                    snapshotId: 7417be09-d419-4ae0-b3fc-7f04a5a71ef1
                    boxId: bx_23456789
                    generation: 0
                    treeAvailable: false
                    truncated: false
                    fileCount: 0
                    totalSizeBytes: 0
                    entries: []
                    reason: legacy_snapshot
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SnapshotId:
      name: snapshotId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Snapshot id returned by the snapshot list/latest calls.
  schemas:
    SnapshotTreeResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - snapshotId
            - boxId
            - generation
            - treeAvailable
            - truncated
            - fileCount
            - totalSizeBytes
            - entries
          properties:
            type:
              type: string
              const: snapshot.tree
            snapshotId:
              type: string
              format: uuid
            boxId:
              type: string
            generation:
              type: integer
            treeAvailable:
              type: boolean
              description: >-
                `false` for legacy snapshots or inventories too large to expand; 
                see `reason`.
            truncated:
              type: boolean
              description: >-
                `true` when the file list was capped; not every entry is 
                returned.
            fileCount:
              type: integer
              description: >-
                Number of your files in this snapshot (base-image system files 
                excluded).
            totalSizeBytes:
              type: integer
              description: >-
                Total bytes of your data in this snapshot (base-image system 
                files excluded).
            entries:
              type: array
              description: >-
                Exactly the files/dirs a resume or download returns — your data 
                only; base-image system entries are not listed.
              items:
                $ref: '#/components/schemas/SnapshotTreeEntry'
            reason:
              type: string
              description: Why the tree is unavailable, when `treeAvailable` is `false`.
              examples:

```

--------------------------------

### Onboard with Box CLI

Source: https://docs.ascii.dev/box/cli-reference

Initiate the full onboarding flow for the Box CLI. This command opens a browser for GitHub OAuth and saves your authentication token.

```bash
box onboard
```

--------------------------------

### Initialize Box SDK with API Key (Python)

Source: https://docs.ascii.dev/box/api-keys

Set up the Box SDK client in Python using an API key from the environment. The Configuration requires the host URL and the access token.

```python
import os
from ascii_box_sdk import ApiClient, Configuration
from ascii_box_sdk.api.box_api import BoxApi

config = Configuration(host="https://ascii.dev/api/box/v1", access_token=os.environ["BOX_API_KEY"])
with ApiClient(config) as client:
    box = BoxApi(client)
    me = box.me()
    print(me.user.login)
```

--------------------------------

### Python SDK Waiters and Helpers Example

Source: https://docs.ascii.dev/box/sdks/python

Demonstrates the usage of various waiter and helper functions from the ascii_box_sdk for managing box states, prompts, and file operations. Use these functions for robust interaction with the box service.

```python
from ascii_box_sdk import wait_until_ready, wait_until_idle, wait_for_desktop, wait_for_prompt, wait_for_prompt_done, stop_and_remove, read_text, write_text, exec_command

wait_until_ready(box, box_id)
queued = box.prompt(box_id, PromptRequest(provider="codex", prompt="Run tests"))
wait_for_prompt(box, box_id, queued.prompt_id)
public_vnc = wait_for_desktop(box, box_id, public_access=True)
write_text(box, box_id, "notes/result.txt", "done\n")
result = exec_command(box, box_id, "cat notes/result.txt")
stop_and_remove(box, box_id)
```

--------------------------------

### Install TypeScript/JavaScript Box SDK

Source: https://docs.ascii.dev/box/sdks/overview

Install the TypeScript/JavaScript Box SDK using npm. This command installs the necessary package for Node.js or browser development.

```bash
npm install @asciidev/box-sdk
```

--------------------------------

### Execute npm Install via SSH (Bash)

Source: https://docs.ascii.dev/box/use-in-code

Installs Node.js dependencies within a Box instance by executing `npm install` via `box ssh`.

```bash
box ssh "$box_id" "cd /home/user/ariana-ide-private && npm install"
```

--------------------------------

### Start and Run Desktop Automation Session

Source: https://docs.ascii.dev/box/desktop-streaming

Use this snippet to initiate a desktop automation task and then run it to completion. The session is recorded automatically.

```bash
box ssh bx_f7k2q9hd
lux start "Open Chrome and test the login flow"
lux run
```

```bash
curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/commands" \
    -H "Authorization: Bearer $BOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command":"lux start \"Open Chrome and test the login flow\" && lux run"}'
```

```typescript
await box.command({
    boxId: "bx_f7k2q9hd",
    commandRequest: { command: 'lux start "Open Chrome and test the login flow" && lux run' },
  });
```

```python
box.command("bx_f7k2q9hd", CommandRequest(
    command='lux start "Open Chrome and test the login flow" && lux run',
))
```

--------------------------------

### Get Operation

Source: https://docs.ascii.dev/box/sdks/typescript

Represents the request parameters for the `get()` method, used to retrieve information about a box.

```APIDOC
## get()

### Description
Retrieves information about a specific box.

### Parameters
#### Path Parameters
- **boxId** (string) - Required - The ID of the box.

### Method
(Not specified, assumed to be part of SDK method call)

### Endpoint
(Not specified, SDK method)

### Request Example
```typescript
{
  "boxId": "string"
}
```

### Response
(Not specified)
```

--------------------------------

### Get box

Source: https://docs.ascii.dev/llms.txt

Poll this endpoint after create, stop, resume, or fork operations to get the current state of the box.

```APIDOC
## GET /boxes/get-box

### Description
Poll this endpoint after create, stop, resume, or fork operations to get the current state of the box.

### Method
GET

### Endpoint
/boxes/get-box

### Parameters
#### Query Parameters
- **boxId** (string) - Required - The ID of the box to retrieve.
```

--------------------------------

### Initialize Box SDK with CommonJS

Source: https://docs.ascii.dev/box/sdks/typescript

Set up the Box API client using CommonJS modules. Configure the base path and access token, defaulting to environment variables.

```javascript
const { BoxApi, Configuration } = require("@asciidev/box-sdk");

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

--------------------------------

### BoxListResult JSON Example

Source: https://docs.ascii.dev/box/use-in-code

An example of the JSON response for a Box listing operation, showing a single Box with its details.

```json
{
  "boxes": [
    {
      "id": "bx_8pqt6dup",
      "name": "Box 2026-05-28 16:00",
      "state": "idle",
      "url": "https://example-box.on.ascii.dev",
      "ip": "203.0.113.10",
      "desktopAvailable": true,
      "desktopUrl": "https://example-desktop.on.ascii.dev/stream.html?hostId=...&token=...",
      "snapshotAvailable": true,
      "snapshotCompletedAt": "2026-05-28T16:39:33.012Z",
      "createdAt": "2026-05-28T16:00:33.143Z",
      "updatedAt": "2026-05-28T16:00:39.535Z",
      "archiveAfter": "2026-05-28T17:00:33.162Z",
      "self": false
    }
  ]
}
```