Skip to content

std/sandbox ​

From the spec

This page is spec/std/sandbox.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).

Limited Weft: code an app's users write (their pages, kept as trees), plugins, an agent's code. It is checked and compiled, and run in its own VM with only what each run gives it: the app's names it may use, the functions and data it is handed, its limits (language.md, Projects; spec/app.md, User trees). The server runtime implements it (server.md).

weft
import { memory, run } from "std/sandbox"
import { money } from "lib/ui/format"

let trees = memory()
try await trees.save("anna", { files: [{ id: "main", source: "import { money } from \"app\"\nexport fn main(caps: { add: (a: number, b: number) => number }, input: json): json { return money(caps.add(1, 2)) }\n" }] })
let three = try await run(trees.tree("anna"), { imports: { money }, caps: { add: (a: number, b: number) => a + b } })
let four = try await run("export fn main(caps: json, input: json): json { return input }\n", { input: 4 })

Trees ​

  • Manifest = { version?, kind?, files: File[], routes?: TreeRoute[] }, File = { id, source, base?, rev? } (ids have no folders), TreeRoute = { path, file?, deleted? } ([id] parameters as in routes/). The version names a compiled tree for caching (letters, digits, ., _, -, at most 64; else a panic); left out, it is a hash of the files and routes. kind is "copies" (layered over the app, the default) or "source" (the user's own project, edited in place). A copy of one of the app's files has a base, { file, rev }: the app's file and its revision when it was copied. rev is the store's: a hash of the source (user-files.md).

  • Stores: memory() (this process's memory), dir(path) (a folder: on the server, or a desktop or mobile app's own storage), database(url) (a SQL database: sqlite:<path>, postgres://…, mysql://…, one table) and a bucket's trees (std/s3, s3.md). Every store is a Store:

    save(name, manifest)checked and compiled, kept and served at once (the draft, if any, goes): Saved = { version }
    saveDraft(name, manifest)kept as the draft, apart from what is served; checked, kept even with problems: { version, problems }
    publish(name)the draft checked and served (fails with Problems when it doesn't check; panics without a draft)
    draft(name), get(name)the draft, what is served (Manifest?, sources included)
    discard(name), delete(name)the draft dropped; the tree and its history gone
    history(name, file), revision(name, file, rev)every version of a file (Version = { rev, at, by?, note?, kind }); its source at one
    copy(name, file)the app's file (its id) copied into the draft with its base; the draft's Manifest
    changes(name)the app's change to each copy since its base: BaseChange = { file, base, rev, app, yours, merged, clean }
    using(keys)the trees the export index finds using any of keys (Card, Card.title, app:money)
    status(name)the API it was checked against, what it uses, its migrations, its fallbacks, the deprecated exports it uses
    tree(name)the Tree ({ store, name }, data) that run and app.serve take

    A name is path segments without . or .., not starting with $ (else a panic). Every function but tree fails with a TreeError (below): Problems when a tree doesn't check, Storage { message } when the store can't be read or written. api() gives what the app exports to user code ({ version, exports, deprecated }).

  • The layout of every store is one (user-files.md, Stores): <name>/manifest.json holds the version, the files ({ id, rev, base? }), the routes, what each file uses of the app, the API it was checked against, its migration state and fallbacks; each revision of a file is <name>/f/<id>/<rev>.weft, its history <name>/h/<id>.json, the draft <name>/draft.json; $index/…, $app/…, $api/… and $deploy.json are the store's own. Saving writes the sources, the index's new entries, then the manifest (a folder's renamed into place), so a reader switches versions at once. A manifest whose files carry their source inline (written by hand), or name sources by version (<name>/v/<version>/<id>.weft, earlier stores), reads too. So a tree copied between a bucket and a device's folder serves as it is; keeping them in step is std/sync's, later (docs/plan.md).

  • Saving checks and compiles. The tree is laid out as an app project (a routed file under routes/ at its path, other components under components/, modules under lib/; imports keep naming files by id) beside the files of what the app's runs import (below, Imports) and what they need (a component of the tree replaces the app's of that name), and checked as sandboxed code. What it uses of the app is recorded (the export index, user-files.md). A tree with problems isn't saved: save fails with Problems { problems } (Problem = { file, line, column, code, message }), and the last good version stays. A route naming no file of the tree is a problem too. check(manifest) gives the problems without saving. So serving and running never compile.

  • What a tree's code may not do (each a problem): import an I/O module (std/http, std/db, std/s3, std/live, std/process, std/fs, std/net: sandbox-io), std/app or std/sandbox, or a component, export or module of the app that no run imports (E1004). It may import std/time (time.md) and std/theme, which read nothing but the clock, and std/regex, std/crypto and std/url (regex.md, crypto.md, url.md), which read nothing but the clock and random bytes.

Imports ​

What user code may use of the app is named per run, in the run's options. A field's label is the name user code sees; its value is the app's own binding:

weft
import FancyCard from "components/ui/FancyCard"
import { cash } from "lib/ui/format"
import * as dates from "lib/ui/dates"

let r = try await run(tree, { imports: { Card: FancyCard, money: cash, dates }, caps: { user } })
let s = try await app.serve(trees, { sandbox: async req => ({ imports: { Card: FancyCard }, caps: { user: … } }) })
weft
// the user's code
import { money } from "app"
import { today } from "app/dates"
---
<Card title={money(today())} />
  • imports is a record of the app's components (with their props), exported functions, values and types, and modules imported whole (every export of lib/ui/dates). { Card } is { Card: Card }. A record literal, or a top-level let holding one, in a run call's options or in the records app.serve's sandbox function returns: the compiler reads them there. E1022 (sandbox-imports) when it can't, or when a value names nothing of the app or the wrong kind of thing (the standard library's, a component under a label without a capital).
  • User code writes labels, never the app's names or files: a component as a tag (<Card>), a function, value or type from the module "app" (import { money } from "app"), a module given whole from "app/<label>". Importing one of the app's files, or a real name no label gives, is a problem of the tree (E1004).
  • The app's own code stays free to change. Renaming cash, moving its file or renaming FancyCard rewrites the value and keeps the label (the edit API's rename turns { money } into { money: cash }), and users' files don't notice. Only a label or a type is the API: changing one is what a migration or a deprecation is for (user-files.md).
  • The app's API for user code is every label any run imports (weft api prints it, user-files.md, The exported API): what a tree is checked against when it is saved, and what the export index and migrations follow. There is no separate list of exports and no permissions object.
  • Each run gets only its own imports. A tree saved against the whole API is run, or served, with what that run imports: a file using something the run doesn't import falls back as a file past a deprecation's date does (a copy is the app's file, a page of the tree's own isn't served and its path falls through to the app); the module a run calls can't, and the run is Refused. Compiled trees are cached by version, the API they use, and the set of labels a run imports. A run that imports nothing gets nothing of the app; neither does a page served without a sandbox function.
  • What the editor lets a user do (its level and palette, docs/editor.md) is a separate value, the edit API's.

Running ​

  • Each compiled tree has a runtime of its own: its own VM, its own module state (a module let mut is the tree's), and its own limits: a tenth of a program's by default (5,000,000 fuel, 8 MB of allocation, 1,000 calls and 100 ms per turn), or what a run's limits says ({ fuel?, memory?, stack?, deadline?, timeout? }).
  • run(code, options?) runs user code: code is a Tree, or a module's source as text (a tree of one module, main, checked and compiled once per text; when it doesn't check the run fails with Problems). options is a plain record given per run, RunOptions = { imports?, caps?, input?, file?, call?, limits? }: it calls the exported function call (main) of the module file (main) with caps and input, as a server function is called: each argument checked against the function's declared parameter types on arrival. It settles with the result (data only), or fails with a RunError. Whatever the user code does, failing, panicking or running out, is an error the app handles: none of it is the app's panic.
  • app.serve's sandbox: req => ({ imports, caps, limits }) gives a user page the same record for each request (app.md, User trees): its caps prop, the names it may use, its limits.
  • Capabilities are all user code reaches: caps is copied in, data as it is (values are values: nothing either side can change is shared), each function as a proxy that calls the app's function as a turn of the app's, with copies of its (data) arguments; what it gives back is copied in the same way, and a task it gives settles the proxy's task when it does. A capability may fail: its error reaches the user code copied, as the proxy's failure. A capability that panics is the app's panic (reported), and the proxy's call panics in the tree. Tasks and handles can't be passed in (a compile error where the checker sees it, else Refused); functions, tasks and handles can't come out (Refused). A proxy works only while its run lasts: called past it (kept in the tree's module state), it panics in the tree.
  • The tree's runtime has no host functions but the proxies and std/time's zone rules and clock: a lib call panics, and there is nothing else to call.
  • An S3 tree is this process's compiled copy of it, checked against the bucket before it serves or runs when the copy is older than the bucket's revalidate (s3.md, User trees in a bucket); a memory, folder or database tree is read as it is (compiled again when its manifest changes). A tree loaded to serve is first brought up to the app (its pending migrations, its fallbacks: user-files.md, Deploys); compiled trees are cached by version and the API they use.

Errors ​

weft
export type TreeError =
  | Problems { problems: Problem[] }                 // save: the tree doesn't check
  | Storage { message: string }                      // the store couldn't be read or written
export type RunError =
  | Missing { message: string }                      // no such tree, file or exported function
  | Problems { problems: Problem[] }                 // code given as text that doesn't check
  | Refused { message: string }                      // an argument that doesn't check against its parameter, a result that isn't data, a module using what the run doesn't import
  | CodeFailed { error: json }                       // the function, or its module's load, failed with `error`
  | Panicked { name: string, message: string }       // the user code panicked
  | Stopped { limit: string, message: string }       // "fuel", "memory", "stack", "deadline" or "timeout" (the run's, 30,000 ms)
  | Storage { message: string }                      // the tree's store couldn't be read

Decided here ​

  1. A tree's runtime is per compiled version and keeps its module state across runs and renders, as a program's does across requests.
  2. Default limits a tenth of a program's; a run's whole time bounded too (timeout).
  3. std/app and std/sandbox are refused in user code beside the I/O modules.
  4. Exported functions of user code get argument-checking entries, as server functions do.
  5. One layout for every store (each file's revisions beside a small manifest, the export index beside the trees), so a device and a server can hold the same tree; serving loads by version and compiles once per process.
  6. User code sees what its run imports of the app, nothing else of it; imports are given per run (owner, 2026-11-17), and the app's API for user code is all of them, found by the compiler. A label is the name user code sees and the value the app's binding, so internal renames never break users' files (platform lead, 2026-11-18).
  7. Drafts are kept apart from what is served, even with problems; publishing checks.
  8. A run's every outcome but success is a RunError value: user code's failures, panics and stops are the app's to handle, never its panics.
  9. A sandbox is made where it runs: run's options (and app.serve's sandbox record) are the whole of it, with no separate permissions object; losing an import works as a deprecation's fallback.

Weft is in development. The reference is the spec as it stands today.