# Numinous Cloud

> Sandboxes for CI, test fleets, and AI agents. Pack an environment into a
> template once. Boot copies in milliseconds. Inject code as read-only ROMs.
> Run with a real Docker daemon inside. Export artifacts even after the
> sandbox dies. The platform enforces TTLs server-side, names every failure
> cause in a machine-readable field (user_* / provider_* / policy_*), meters
> by the second under your labels, and shows reservable capacity. Nothing is
> preemptible. Seconds lost to provider_* causes are never billed.

Key facts:
- Install: `curl -fsSL https://cloud.numinous.technology/install.sh | sh` or `pip install numinous` (SDK + `numinous` CLI)
- Auth: `Authorization: Bearer nk_...`; env vars NUMINOUS_API_URL / NUMINOUS_API_KEY
- Errors: `{"detail": {"cause": "...", "message": "..."}}`; causes are machine-readable
- Core loop: pack template, boot (launch_token idempotency), exec, export, destroy (returns teardown_proof)
- Also: checkpoint a running sandbox into a template (fork), opt-in auto_suspend_idle_seconds with auto-wake on exec, per-sandbox observed-usage metrics, whoami
- Pricing: CPU $0.06/vCPU-hr, memory $0.008/GiB-hr, GPU (H100/H200) at market, storage $0.08/GiB-mo, suspended $0.12/GiB-mo, egress $0.02/GiB (free to own in-region S3)

## Docs

- [Quickstart](https://cloud.numinous.technology/docs): install, authenticate, pack a template, boot/run/export/destroy
- [Templates & ROMs](https://cloud.numinous.technology/docs/templates): templates hold the weight (snapshotted warm environments), ROMs carry the change (content-addressed read-only bundles at /rom)
- [Lifecycle & failures](https://cloud.numinous.technology/docs/lifecycle): states, typed causes, hard TTLs, idempotent create, teardown proof, export-after-death, suspend/resume
- [Networking](https://cloud.numinous.technology/docs/network): egress allow | deny | allowlist as a create argument; private registries; static egress IPs
- [Metering & capacity](https://cloud.numinous.technology/docs/metering): per-second usage spans queryable by label; capacity API and reservations; webhooks
- [Guarantees](https://cloud.numinous.technology/docs/guarantees): the contract, including unbilled provider faults and non-preemptibility
- [Pricing](https://cloud.numinous.technology/docs/pricing): full rate table
- [HTTP API](https://cloud.numinous.technology/docs/api): endpoint reference generated from OpenAPI
- [Python SDK](https://cloud.numinous.technology/docs/sdk): client, resources, fan-out pattern, typed errors
- [CLI](https://cloud.numinous.technology/docs/cli): commands, JSON output, exit codes (75 = retryable provider fault)

## Machine-readable

- [OpenAPI spec](https://cloud.numinous.technology/openapi.json): the full HTTP surface; also served live at GET /openapi.json on the control plane
- [Install script](https://cloud.numinous.technology/install.sh)
- [Python SDK source](https://github.com/numinous-technology/numinous-python)

## Agent setup prompt

Set up Numinous Cloud in this repository.
1. Run: curl -fsSL https://cloud.numinous.technology/install.sh | sh
2. Ask the user for NUMINOUS_API_URL and NUMINOUS_API_KEY, export them.
3. Verify with: numinous capacity && numinous pricing
4. Reply exactly "numinous is connected" when every step succeeds.