Adding a Sandbox

Sandboxes are pre-seeded playground environments that open with files, environment variables, and a start command already loaded. Each sandbox is a static JSON file stored in web/docs/src/data/sandboxes/.

1. Create the JSON manifest

Add a file at src/data/sandboxes/your-example.json:

{
  "id": "your-example",
  "title": "Your Example Title",
  "description": "One sentence describing what this sandbox demonstrates.",
  "files": {
    "/index.sh": "#!/bin/sh\necho 'Hello ɳSelf'\nnself --version\n"
  },
  "env": {
    "TERM": "xterm-256color"
  },
  "startCommand": "sh /index.sh"
}

2. Schema reference

Field	Type	Required	Description
`id`	string	Yes	URL-safe slug, alphanumeric + hyphens. Must match the filename.
`title`	string	Yes	Human-readable title shown in the sandbox header.
`description`	string	No	Short description shown below the title.
`files`	object	Yes	Map of absolute paths to file content strings. These are mounted into the WebContainer.
`env`	object	Yes	Environment variables injected when running commands. Always include `TERM: "xterm-256color"`.
`startCommand`	string	Yes	Command run automatically after mount. Use `"sh /index.sh"` for multi-step setups.

3. Link to the sandbox

The sandbox is automatically reachable at /sandbox/your-example. To add it to the sidebar navigation, edit src/lib/docs/navigation.ts and add an entry under the Playground section:

{ title: 'Your Example', href: '/sandbox/your-example' }

4. Inline "Open in Sandbox" button

To show an "Open in Sandbox" button below a code block in an MDX doc page, set the sandbox frontmatter property to the sandbox ID:

---
sandbox: your-example
---

The button only appears on code blocks where the language is sh or bash.

Allowed and blocked commands

The sandbox blocks a small set of patterns for safety:

rm -rf /: Filesystem wipe
curl / wget to external hosts (only nself.org is allowed)

Everything else runs normally inside the WebContainer. Docker commands are simulated, ɳSelf CLI calls that require Docker will show a sandbox-mode notice.