Sandboxes: how your scripts run
Partly liveHow a published package runs: one sandbox per creator and experience in each world, its budgets, and what stops it.
#Sandboxes: how your scripts run
Every package you publish runs in its own sandbox on each world that installs it.
#What a sandbox is
A sandbox is one VM (QuickJS-ng in x1script.wasm, on wasmtime) per world and experience: earth/fishing-ada.
It has its own memory, globals, timers, budgets and log. Nothing is shared with other creators' sandboxes. They reach each other only through the bus, using grants. A crash, a runaway loop or a memory bomb in one sandbox stops that sandbox only. It never stops another sandbox or the server tick.
#Budgets (community tier)
| What | Limit | Past it |
|---|---|---|
One handler, task or await continuation | 5 ms or 500,000 VM steps | It is stopped (try/catch can't keep it running) and counts 1 strike |
| One call from the host into your VM | 50 ms | Stopped; at 4× this, the engine traps the VM |
| JS heap | 16 MiB | The VM is terminated |
| Main-thread time | 2 ms per tick, averaged over 1 s | Throttled: events wait and steps pause until you are under 80 % |
| Host calls | 100/s (burst 200) | The call throws rate limited |
| Events in | 200/s, queue 512 | The oldest droppable events (Heartbeat, Chat, region moves) are dropped |
| Pending tasks / signal connections | 1,000 each | task.* / Connect throw RangeError |
| Data store | 16 stores, 1,000 keys per store, 4 MiB in all, 64 KiB per value | The write fails |
| Bus | 5 publishes/s (burst 30), 16 KiB per message | 429 |
Per creator and world, you get at most 4 sandboxes, 48 MiB of heap and 4 ms per tick in all.
What happens when a sandbox misbehaves:
- Strikes: ten strikes within a minute terminate the VM.
- Crashes: a terminated or trapped VM restarts after 10 s, then after 60 s, then after 300 s. The third crash within an hour suspends it until an operator resumes it, or until a new version is approved.
- Throttling: 30 s of throttling within 5 minutes suspends the sandbox for 5 minutes. The second time, it stays suspended until an operator resumes it.
#What you can use
Your manifest (x1.json) asks for capabilities, and the approver grants some or all of them. The full list, with every call, parameter, limit and error, is in the Capabilities reference. The grant comes in Host.capabilities, and Host.Supports("inventory") tells you whether you have one. A call outside your grants throws a CapabilityError naming the capability:
import { Chat, CapabilityError, Host } from "@x1/script";
try { Chat.Broadcast("hi"); } catch (e) { if (e instanceof CapabilityError) print(`no ${e.capability} here`); }
print(Host.sandbox?.id, Host.Usage().cpuMsLastSecond);Two smaller APIs:
Host.Usage()shows your memory, CPU, calls and strikes against your budgets.Random.create(seed)gives the same draws on every host.
#Logs
print, warn and console.* write to your sandbox's log on each host. Your warnings and errors also reach the server's log, rate-limited, and 0x sees the last lines, the last error and your budget counters when it looks into a problem with your package. To watch your budgets from inside, call Host.Usage().
#When 0x steps in
0x can suspend, resume, restart or stop a sandbox, and can raise one install's budgets up to 4× the tier's. A sandbox suspended by the crash or throttle rules above stays suspended until 0x resumes it or a new version of yours is approved. For a version-wide stop (the kill switch, rollback, revoke), see Publishing: after approval.
