Compute that stays
out of your way.

Quickstart

Install the CLI, create an invite-gated account, SSH in, then stop without losing the disk.

1. Install the CLI

curl -fsSL https://tinybox-control-plane.ramasamy-vignesh.workers.dev/install | sh
export PATH="$HOME/.tinybox/bin:$PATH"

Windows: irm https://tinybox-control-plane.ramasamy-vignesh.workers.dev/install.ps1 | iex

2. Signup (friends beta)

Ask the operator for the shared invite token, then:

tinybox signup --email you@example.com --invite <token>
tinybox status

Signup returns an API key once and grants trial machine-time. Existing users: tinybox login tb_…

3. Create a box

tinybox new --type small --name first-box --ttl 900
tinybox list
tinybox info current

small is 2 vCPU / 4 GB (0.5× machine-time). default is 4 vCPU / 8 GB.

4. Work, stop, resume

tinybox ssh current
tinybox stop current
# wait until state is archived
tinybox resume current
tinybox delete current

Stop writes a verified snapshot before the box is archived (abort-stop). Periodic snaps run about every minute while the box is running.

Machine capabilities

Two predictable x86_64 shapes for the first release.

Base image

Boxes start from a baked Ubuntu x86_64 template with OpenSSH, qemu-guest-agent, Docker, Git, Node, Python, and common CLI tools.

What is not included yet

GPU support, ARM images, Windows/macOS guests, and process-memory snapshots are outside the initial release. Dedicated public IPs are in procurement.

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 needed to resume and fork. TinyBox takes them about every minute while a box runs, plus a verified stop snapshot on archive.

• Periodic — ~1 minute while running (Proxmox disk snaps).
• Stop — required for abort-stop; a stop that cannot snapshot never succeeds.
• Contain user files, packages, config, and Docker named volumes.
• Do not contain running process memory, hostname, network identity, or SSH host keys.

Billing

Subscription machine-time with carry-forward — unused seconds accumulate; stopped boxes are free.

Friends beta may grant trial seconds at signup. Use tinybox limits, GET /billing/usage, and GET /billing/transactions.

FAQ