0xDocs 0x.limo

Docs / Scripting

Sandboxes: how your scripts run

Partly live

How 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)

WhatLimitPast it
One handler, task or await continuation5 ms or 500,000 VM stepsIt is stopped (try/catch can't keep it running) and counts 1 strike
One call from the host into your VM50 msStopped; at 4× this, the engine traps the VM
JS heap16 MiBThe VM is terminated
Main-thread time2 ms per tick, averaged over 1 sThrottled: events wait and steps pause until you are under 80 %
Host calls100/s (burst 200)The call throws rate limited
Events in200/s, queue 512The oldest droppable events (Heartbeat, Chat, region moves) are dropped
Pending tasks / signal connections1,000 eachtask.* / Connect throw RangeError
Data store16 stores, 1,000 keys per store, 4 MiB in all, 64 KiB per valueThe write fails
Bus5 publishes/s (burst 30), 16 KiB per message429

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:

ts
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.