# Sistemo

> Run AI agents and untrusted code in real Firecracker microVMs on Sistemo Cloud (prepaid EU). Each sandbox is a full VM with its own kernel, not a shared-kernel container.

Key facts for assistants:
- A "sandbox" and a "machine" are the same thing: `Machine` is the API/dashboard resource noun; `Sandbox` is the SDK ergonomic for create-run-destroy.
- Auth uses API keys: `Authorization: Bearer sk_live_…`. A `full`-scope key can create/run; a `read` key can only list.
- Base URL: `https://api.sistemo.io` (override with `SISTEMO_BASE_URL`).
- Core primitive: a guest job. SDK `sb.run(script, timeout=120)` is start+wait (`POST /v1/machines/{id}/execs` then poll). Ceiling 24h. Caller mints `exec_id`.
- Billing is a prepaid wallet (€5 free · €30 trial with card), not a subscription. Metered **per second**: vCPU + RAM while `running` (€0.035/vCPU-hour, €0.012/GiB-hour); disk and snapshots while they exist (€0.050/GB-month sticker, prorated). No 1-hour minimum. Stopped = €0 compute, disk still bills.
- No sandbox auto-stop or idle timeout: a machine runs until you destroy it or the balance hits €0. The wallet is the cap.
- Known limits: command timeout default 120s, max 24h, enforced in the guest (exit 124). Output 32 MiB per stream with a `truncated` flag. No file API, no GPUs, no region choice. `cmd &` inside a script does not detach.
- The Activity log (GET /v1/activity) records metadata only — never script text, never output.
- Full concatenated docs: /llms-full.txt

## Get started
- [What is Sistemo](https://docs.sistemo.io/get-started/): the 10-line version and how the pieces fit.
- [Core concepts](https://docs.sistemo.io/get-started/concepts/): machine vs sandbox, microVM, lifecycle, volumes, images, scopes.

## Cloud
- [Cloud overview](https://docs.sistemo.io/cloud/): the managed product.
- [Cloud quickstart](https://docs.sistemo.io/cloud/quickstart/): get a key and run code in under 10 minutes.
- [API keys](https://docs.sistemo.io/cloud/api-keys/): create, scope, and revoke keys.
- [Usage & billing](https://docs.sistemo.io/cloud/usage-billing/): prepaid wallet, rates, grace window.
- [Snapshots](https://docs.sistemo.io/cloud/snapshots/): disk snapshot, restore, deploy-from.
- [Activity log](https://docs.sistemo.io/cloud/activity/): who did what, on every tier; metadata only, never script text or output.
- [Terminal](https://docs.sistemo.io/cloud/terminal/): browser shell into a running machine.

## Cookbook
- [Run an AI agent's code](https://docs.sistemo.io/cookbook/run-agent-code/): execute LLM-generated code safely, then destroy.
- [Connect an LLM](https://docs.sistemo.io/cookbook/connect-an-llm/): give Claude/OpenAI a sandbox as a code-execution tool.
- [Install packages](https://docs.sistemo.io/cookbook/install-packages/): pip/npm inside a sandbox.
- [Get files in and out](https://docs.sistemo.io/cookbook/files/): no file API — heredoc, base64, presigned URL, volume; output 32 MiB per stream with a `truncated` flag.
- [Long-running work](https://docs.sistemo.io/cookbook/long-running/): `sb.run(..., timeout=3600)` waits; `/execs` for stream/reconnect.
- [Persist data with volumes](https://docs.sistemo.io/cookbook/persist-data/): keep data across destroy/recreate.

## SDKs
- [SDKs overview](https://docs.sistemo.io/sdk/): zero-dependency Python and JS/TS clients; configuration.
- [Python: install & overview](https://docs.sistemo.io/sdk/python/)
- [Python: quickstart](https://docs.sistemo.io/sdk/python/quickstart/)
- [Python: Sandbox API](https://docs.sistemo.io/sdk/python/sandbox/)
- [Python: error handling](https://docs.sistemo.io/sdk/python/errors/)
- [Python: examples](https://docs.sistemo.io/sdk/python/examples/)
- [JavaScript: install & overview](https://docs.sistemo.io/sdk/javascript/)
- [JavaScript: quickstart](https://docs.sistemo.io/sdk/javascript/quickstart/)
- [JavaScript: Sandbox API](https://docs.sistemo.io/sdk/javascript/sandbox/)
- [JavaScript: error handling](https://docs.sistemo.io/sdk/javascript/errors/)
- [JavaScript: examples](https://docs.sistemo.io/sdk/javascript/examples/)

## API reference
- [API overview](https://docs.sistemo.io/api/): base URL, conventions, endpoints at a glance.
- [Authentication](https://docs.sistemo.io/api/authentication/): Bearer keys and scopes.
- [Machines](https://docs.sistemo.io/api/machines/): create/list/get/stop/start/delete.
- [Exec](https://docs.sistemo.io/api/exec/): jobs at `/execs`; `sb.run()` waits.
- [Volumes](https://docs.sistemo.io/api/volumes/): persistent disks.
- [Snapshots](https://docs.sistemo.io/api/snapshots/): take/list/restore/delete.
- [Images](https://docs.sistemo.io/api/images/): the stack catalog (base/python/node/ai/debian13/ubuntu26.04).
- [Activity](https://docs.sistemo.io/api/activity/): the audit feed — filters, keyset pagination, per-action metadata.
- [Quotas](https://docs.sistemo.io/api/quotas/): the five independent limits with current usage.
- [Billing & usage](https://docs.sistemo.io/api/billing/): balance, rates, usage totals, per-resource cost.
- [API keys](https://docs.sistemo.io/api/api-keys/): manage keys.
- [Errors](https://docs.sistemo.io/api/errors/): status codes and error codes.

## Changes and status
- [Changelog](https://docs.sistemo.io/changelog/): dated API and SDK changes, breaking ones marked.
- [Service status](https://status.sistemo.io): live API and fleet status.

## FAQ
- [FAQ](https://docs.sistemo.io/faq/): sandbox lifetime, €0 behaviour, reconnecting, limits, cost, privacy.