Skip to content

README.md

Latest commit

 

History

History
142 lines (107 loc) · 4.84 KB

README.md

File metadata and controls

142 lines (107 loc) · 4.84 KB
Raw

BoxLite Box API Reference Server

Reference implementation of the BoxLite Box API. Use this to validate client implementations against the spec.

Box responses include the native SDK's persisted privileged mode when known. REST clients use it to verify named get_or_create reuse; a missing value is unknown and cannot establish a match with either requested mode.

Not production-ready — no persistence, single-tenant.

Setup

# 1. Build the BoxLite Python SDK (installs into project .venv)
make dev:python

# 2. (Optional) Copy server defaults for local development
cp openapi/reference-server/.env.example openapi/reference-server/.env

# 3. Start the server (uv installs server deps, --active uses the project .venv)
cd openapi/reference-server
uv run --active server.py

Authentication

By default the server accepts any non-empty Authorization: Bearer <token> header (format-agnostic, matching the spec's BearerAuth scheme — token issuance and real validation are out of scope for a reference server). GET /v1/config needs no auth; every other endpoint requires a non-empty bearer.

Set BOXLITE_SERVER_API_KEY to require an exact key: the bearer must then equal it (constant-time check) or the request gets 401. A missing/empty bearer is always 401 regardless. This lets clients exercise both the success and failure auth paths against the reference server.

Quick Test

# The reference server accepts any non-empty bearer
TOKEN=dev-token

# Server config (no auth required)
curl -s http://localhost:8080/v1/config | python3 -m json.tool

# Identity + scopes for the calling credential
curl -s http://localhost:8080/v1/me \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# Create a box
curl -s -X POST http://localhost:8080/v1/demo/boxes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"alpine:latest"}' | python3 -m json.tool

# List boxes
curl -s http://localhost:8080/v1/demo/boxes \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# Start a box (replace BOX_ID)
curl -s -X POST http://localhost:8080/v1/demo/boxes/$BOX_ID/start \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# Execute a command
curl -s -X POST http://localhost:8080/v1/demo/boxes/$BOX_ID/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"echo","args":["hello world"]}' | python3 -m json.tool

# Stream output (WebSocket /attach — see SDK)

# Runtime metrics
curl -s http://localhost:8080/v1/demo/metrics \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# Remove box
curl -s -X DELETE http://localhost:8080/v1/demo/boxes/$BOX_ID \
  -H "Authorization: Bearer $TOKEN" -w "%{http_code}\n"

Implemented endpoints

Endpoint Method Description
/v1/config GET Server configuration
/v1/me GET Identity + scopes for the credential
/{prefix}/boxes POST Create box
/{prefix}/boxes GET List boxes
/{prefix}/boxes/{id} GET Get box
/{prefix}/boxes/{id} HEAD Check exists
/{prefix}/boxes/{id} DELETE Remove box
/{prefix}/boxes/{id}/start POST Start box
/{prefix}/boxes/{id}/stop POST Stop box
/{prefix}/boxes/{id}/exec POST Execute command
/{prefix}/boxes/{id}/executions/{eid} GET Execution status
/{prefix}/boxes/{id}/executions/{eid}/signal POST Send signal
/{prefix}/boxes/{id}/executions/{eid}/resize POST Resize TTY
/{prefix}/boxes/{id}/files PUT Upload files
/{prefix}/boxes/{id}/files GET Download files
/{prefix}/boxes/{id}/metrics GET Box metrics
/{prefix}/metrics GET Runtime metrics

Not implemented: the /{prefix}/images… and /{prefix}/images/registries… routes, WebSocket TTY.

CLI Options

uv run --active server.py [--env-file /path/to/.env] [--host 0.0.0.0] [--port 8080] [--log-level info]

Environment Configuration

The server supports openapi/reference-server/.env by default. Use --env-file to load a different file.

Server Settings (BOXLITE_SERVER_*)

Variable Default
BOXLITE_SERVER_HOST 0.0.0.0
BOXLITE_SERVER_PORT 8080
BOXLITE_SERVER_LOG_LEVEL info
BOXLITE_SERVER_JWT_SECRET boxlite-reference-server-secret
BOXLITE_SERVER_JWT_EXPIRY_SECONDS 3600
BOXLITE_SERVER_API_KEY (unset → permissive; set → exact-match required)

Runtime Settings (BOXLITE_RUNTIME_*)

Variable Default
BOXLITE_RUNTIME_HOME_DIR ~/.boxlite
BOXLITE_RUNTIME_IMAGE_REGISTRIES mirror.gcr.io,docker.io

Precedence

For host, port, and log-level:

  1. CLI args (--host, --port, --log-level)
  2. Environment (BOXLITE_SERVER_*)
  3. Built-in defaults