Compute that stays
out of your way.

Quickstart

Create a persistent Linux environment, connect over SSH, and stop it when you are done.

1. Build or install the CLI

From the tinybox repository, build the Go CLI:

go build -o tinybox ./cmd/tinybox

2. Authenticate

Create an API key in the dashboard, then sign in:

./tinybox --api-url https://tinybox-control-plane.ramasamy-vignesh.workers.dev/v1 \
  login tb_your_api_key

3. Create a box

./tinybox new --name first-box
./tinybox list
./tinybox info current

A default box is 4 vCPU and 8 GB RAM. The API returns provisioning while the host prepares it, then transitions to a runnable state.

4. Work and stop

./tinybox ssh current
# work inside the VM
./tinybox stop current

Stopping creates a snapshot and pauses machine-time billing. Resume later with ./tinybox resume current.

Machine capabilities

Two predictable x86_64 shapes are planned for the first release.

Base image

Boxes start from an Ubuntu x86_64 image with OpenSSH, cloud-init, Docker, Git, Node.js, Python, and common command-line tools. The image and host provisioning are managed by the orchestrator.

What is not included yet

GPU support, ARM images, Windows/macOS guests, and process-memory snapshots are deliberately outside the initial release.

REST API

The API is a JSON control plane for boxes, snapshots, events, files, hosting, and billing.

Base URL

https://tinybox-control-plane.ramasamy-vignesh.workers.dev/v1

Authentication

Authorization: Bearer tb_your_api_key

Core endpoints

Response shape

{
  "ok": true,
  "type": "box.created",
  "box": { "id": "tb_...", "state": "provisioning" }
}

Errors retain the HTTP status and include a stable error code, such as unauthorized, not_found, or orchestrator_unavailable. The complete machine-readable contract is available in the repository's openapi.yaml.

CLI reference

The tinybox CLI is designed for humans and shell automation.

Automation

Pass --json for stable machine-readable output. Set TINYBOX_API_URL to target another control plane. Configuration lives at ~/.config/tinybox/config.json with restrictive permissions.

Python SDK

The dependency-free Python client uses typed dataclasses and snake_case methods.

python -m pip install tinybox-sdk

from tinybox_sdk import TinyboxClient

client = TinyboxClient(api_key="tb_...")
box = client.create(name="python-worker")
result = client.command(box.id, "echo hello")
print(result.stdout)

Configure with TINYBOX_API_KEY and TINYBOX_API_URL. HTTP failures raise TinyboxHTTPError; connection failures raise TinyboxConnectionError.

TypeScript SDK

The Fetch-compatible client works in Node and browsers with camelCase methods.

npm install @tinybox/sdk

import { TinyboxClient } from "@tinybox/sdk";

const client = new TinyboxClient({ apiKey: "tb_..." });
const box = await client.create({ name: "web-worker" });
console.log(box.id, box.state);

Use TinyboxHttpError for API failures and TinyboxConnectionError for network and timeout failures.

SSH access

Boxes are standard Linux machines. The CLI manages the SSH connection details.

tinybox ssh tb_abc123
tinybox ssh tb_abc123 "cd app && npm test"
tinybox scp ./build.zip tb_abc123:/home/user/

SSH keys should be injected with POST /boxes/{id}/sshkey. SSH is available only after the VM is running and has an assigned IP address.

Hosting

Expose a service through a token-gated HTTPS route without opening a public firewall rule yourself.

tinybox host tb_abc123 3000 --title "App preview"
# private URL by default
tinybox host tb_abc123 3000 --public

Private routes include an _token query parameter. The proxy strips the token before forwarding and accepts only upstream targets registered by the host orchestrator. Custom domains are not configured yet.

Template boxes

Bake a development environment once, then fork it for users, tasks, or CI runs.

tinybox stop tb_source
tinybox template create tb_source --name "Node baseline"
tinybox template fork tpl_abc123 --name customer-1 --no-env

A template requires a stopped box with a completed snapshot. Update it by resuming the source, making changes, and stopping it again. Future forks use the newest snapshot.

Snapshots

Snapshots preserve the filesystem state needed to resume and fork a box.

• Created when a box is stopped.
• Contain user files, installed packages, system configuration, and Docker named volumes.
• Do not contain running process memory, hostname, network identity, or SSH host keys.
• Serve as the source for template forks.

Process-level snapshots and downloadable snapshot archives are later roadmap items.

Billing

Prepaid machine-time credits make cost predictable.

Credits are deducted from lifecycle usage events. Stopped boxes do not consume machine time. Stripe Checkout and signed webhooks support credit purchases when billing secrets are configured.

Use tinybox limits, GET /billing/usage, and GET /billing/transactions to inspect usage.

FAQ