ariana-dot-dev/kimi-box-plugin/box-platform

Build a platform on Box

For products where each of your users gets a sandbox (agent platforms, preview services, CI fleets). You run your own backend and database and drive Box through the API/SDKs (see box-api, box-sdk-typescript, box-sdk-python skills).

The two rules

1. Always create user boxes with `no_env` / `--no-env`. A no-env box receives none of your account's secrets or credentials and cannot act on your account or other boxes. Pass what it needs explicitly with env.
2. Tag each box with per-box env vars (e.g. env: { TENANT_ID: "acme" }) so your backend can identify it.

box new --no-env --no-auto-stop --env TENANT_ID=acme

Wait for state ready or idle before sending commands — earlier commands run before env is applied.

Architecture patterns (cost per user)

• One always-on box per project — simplest, perfectly isolated. ~$26/mo per box running 24/7 ($0.036/h). Use when the project has real traffic.
• One always-on box per user — all of a user's projects in folders on one box, a small daemon multiplexes agent sessions. ~$26/mo per user; works to ~5–10 projects/user. Weaker isolation between projects.
• Stop/resume around usage (what most platforms end up with) — box runs only while the user works: resume on message (seconds), relaunch daemon + preview, stop after a short idle countdown. Typical user $1–5/mo, power user $10–20. Refinements: publish builds to a CDN so preview never depends on a live box; answer instantly from your own server while the box resumes.

Provision from a template (never install per user)

box new                        # install runtimes, deps, your daemon once
box stop <template-id>         # its snapshot is now the template
box fork <template-id> --no-env    # per user, a few seconds, ~constant cost

Forks inherit the whole filesystem (files, packages, enabled systemd services, Docker named volumes) and always take the latest snapshot. Per-fork env is API/SDK only (CLI fork takes --no-env alone). Update a template by resuming → changing → stopping it. Warm it before publishing: resume, run your app's normal boot once, stop — the box learns the read order and prefetches.

Bring your own harness: the daemon pattern

box prompt (Claude Code / Codex) is optional. For full control, run a small HTTP daemon inside the box:

1. Install it (box scp the binary, or bake it into the template).
2. Keep it alive as an enabled systemd service so it survives stop/resume/fork (unit files under /etc are snapshotted).
3. Expose it with host <port> --private; treat the _token URL as the daemon's credential.
4. Drive it from your backend over plain HTTPS.

Skip the daemon when one-shot calls suffice: POST /boxes/{id}/commands runs anything (including in-box tools host and lux), file endpoints read/write, first-class endpoints cover lifecycle/prompts/events/desktop/snapshots. A daemon earns its place for streaming, concurrency, or lower latency.

Facts that shape the design

• Snapshots: incremental, every minute while ready/idle + final on stop; resume/fork usable in seconds regardless of size; kept for the life of the box. Capture /home/user, Docker named volumes, and your changes under /etc /usr /opt /root /srv; not running processes or machine identity.
• Process survival: stop/resume/fork = reboot. Enabled systemd services come back; hand-run processes do not. Keep setup/start idempotent.
• Billing: per-second, only while running ($1 ≈ 27.7 h). Stopped boxes are free. Plans set active-box caps (100/200/800/1200) and creations-per-minute (10/20/35/60); trial: 4 active, 5/min, 20/day. Credit packs never expire; plan time resets monthly.
• Secrets: dashboard env vars + secret files apply to every box and push to live boxes on save; per-box env overrides per key. Never pass secrets in prompts, URLs, or CLI args.
• Hosting: in-box host <port> gives https://<box>-<port>.on.ascii.dev (token-gated default, --public opens, sticky across resume). App must bind 0.0.0.0. Up to 50 ports per box.
• Machine: 4 shared vCPU / 8 GB / 75 GB NVMe, x86_64 Ubuntu, dedicated IPv4, EU regions only. Not for GPU or sustained 100% CPU.

Sizing

Concurrent boxes track daily actives, not signups: 10,000 signups ≈ 100 DAU ≈ 10–100 concurrent boxes, up to 10× on launch day. Pick the plan whose active-box cap and creations/minute cover launch peak; upgrade from the dashboard.

Docs: https://docs.ascii.dev/box/platform-guide