Skip to content

Sandbox and limits

Restrict an Elide program's filesystem, network, subprocess, thread and native access with --sandbox and --allow-* flags, and limit resources and run time.

Read offlineelide help sandbox

On this page

Programs run unrestricted until you pass a sandbox flag. --sandbox denies filesystem access and subprocesses; the network stays allowed until you list hosts:

Terminal
bash
elide --sandbox --allow-read=. --allow-net=example.com run app.js
elide --sandbox — filesystem, network and subprocess policy
 ~/demo  elide [...]
[elide.fs] allow read fs /home/demo/demo
[elide.fs] allow read fs /home/demo/demo/app.mjs
[elide.fs] allow read fs /home/demo/demo/app.mjs
[elide.fs] DENY  read stat ./data/config.json
[elide.fs] DENY  read open ./data/config.json
read : EACCES: permission denied, open './data/config.json'
fetch: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
spawn: spawn of 'uname' is not permitted; grant it with --allow-run=uname
 ~/demo  elide [...]
read : { "region": "eu-west-1", "replicas": 3 }
fetch: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
spawn: spawn of 'uname' is not permitted; grant it with --allow-run=uname
 

Java and Kotlin are not sandboxed

Elide currently runs Java and Kotlin programs on HotSpot, which the sandbox does not cover. --sandbox and the --allow-*, --deny-* and --no-native restrictions are refused before Java/Kotlin compilation or execution.

The sandbox covers programs run with elide run, elide python, elide serve and elide <file>. With --sandbox, --allow-read, --allow-write, --allow-net, --allow-run, --deny-net, --deny-run or --no-native, everything else that runs code or tools exits with code 2 before it starts:

  • Java and Kotlin programs, Android apps, Pkl and Markdown documents, and project scripts run with elide run
  • elide serve of a directory, which serves its files from the host
  • elide java, javac, kotlinc, jar, native-image and the other JVM and native tools
  • every other subcommand, such as build, test, format, install, uv, dev, mcp and repl, and a bare elide that opens the REPL

elide help and elide info ignore these flags. Grants that restrict nothing, such as --allow-read --allow-write together or a bare --allow-net or --allow-run, are not refused.

The restrictions apply to the program, not to what you ask Elide to do for you. The program can always read the entry file you name and list the names in its directory, even outside --allow-read; the other files in that directory stay denied. These options act outside the program’s grants:

  • reading an @file argument list or an --env-file
  • writing diagnostics: --heap-dump, --jfr, --jitdump, --coverage, and engine options set with -D or --vm, such as a log file
  • sending telemetry to --otel-endpoint
  • listening for a debugger on --debugger-host

The legacy capability flags coordinate filesystem operations made by restricted guest contexts. They do not isolate the host process from other programs that can modify the same files. Keep granted directories private from untrusted native processes; use an OS sandbox for that boundary. The stronger sandboxed and isolated profiles remain unavailable and are refused rather than falling back to legacy restrictions.

Allow file access

Terminal
bash
elide --allow-read=. --fs-audit run app.js
text
[elide.fs] allow read open hello.txt
[elide.fs] DENY  write open out.txt
utf-8 · text · Lines: 2

A denied access fails like a protected file: EACCES: permission denied, open 'hello.txt'. Relative paths resolve from the working directory.

WASI programs cannot access host directories until you map one with WasiMapDirs; see WebAssembly. These grants apply to mapped directories, and a WASI open needs both read and write access.

Allow network and subprocesses

Terminal
bash
elide --allow-net=localhost --allow-run=ls run app.js

A subprocess runs with your own access, outside the sandbox, so --sandbox, --allow-read and --allow-write deny every subprocess until --allow-run names the commands, or allows all of them when bare. --deny-run alone does not allow any. Before 1.6.4, these flags left subprocesses allowed; add --allow-run to keep that.

A denied call names the grant it needs:

text
TypeError: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
Error: spawn of 'echo' is not permitted; grant it with --allow-run=echo
utf-8 · text · Lines: 2

A --deny-* match reports denied by --deny-net or denied by --deny-run. Policy checks the command that runs, so a shell invocation is checked as sh. Spawn with execFileSync from node:child_process.

Threads and native access

Program Threads by default Native access by default
JavaScript, TypeScript Not applicable: node:worker_threads workers run under every flag Allowed
Python entry Allowed Allowed
Python entry with --sandbox or an --allow-read/--allow-write grant Denied; add --allow-threads Allowed
Python under --interop Denied, even with --allow-threads Allowed
python
# threads.py
import threading
out = []
t = threading.Thread(target=lambda: out.append("worker ran"))
t.start(); t.join()
print(out[0])
utf-8 · python · Lines: 6
Terminal
bash
elide python threads.py                                         # worker ran
elide --sandbox --allow-read=. python threads.py                # Creating threads is not allowed.
elide --sandbox --allow-read=. --allow-threads python threads.py  # worker ran

--no-native denies native access. Python then lacks some features, such as AF_UNIX sockets (AttributeError: module 'socket' has no attribute 'AF_UNIX') and arbitrary signals, and starts more slowly. --allow-native states the default explicitly; combining it with --no-native is a usage error (exit 2).

Python child processes

A Python program that runs sys.executable, as multiprocessing’s spawn start method and Metaflow do, starts Elide’s Python again with the same flags. The child sees the environment the program passed it (its os.environ unless it passes env), so it needs no --allow-env of its own. Started through another program such as a shell, the child keeps the restrictions but not the environment.

Under a restricted parent, the child runs only programs (elide run, elide python, elide FILE) whose file the parent may read, in the parent’s working directory or one it may read. Each of these exits with code 2:

  • other subcommands such as java or uv, a project run (elide run with no file) and script names
  • a file outside the parent’s --allow-read, or a working directory outside it other than the parent’s own
  • @argfiles, --use-version, --env-file, --properties-file and --project
  • flags that write files, listen or connect on the host, such as --heap-dump, --jfr, --jitdump, --coverage, --debugger, --otel-endpoint, --redirect-warnings and -D/-X engine options
  • a grant the parent lacks such as --allow-read, and a different --sandbox profile

The child ignores ELIDE_* and OTEL_* variables, NODE_REDIRECT_WARNINGS and NODE_EXTRA_CA_CERTS in its environment, and loads no .env, .properties or .elideversion file.

Other programs the child or the parent starts are not sandboxed. Limit them with --allow-run. --allow-run=elide permits only the running Elide binary, started through sys.executable or process.execPath, and no other file named elide:

Terminal
bash
elide --sandbox --allow-read=. --allow-run=elide python app.py   # subprocesses are Elide's Python, reading only .

Set limits

--limit applies to JavaScript and TypeScript programs. A value is a number, 0 to forbid, or unlimited, the default. Other names, languages or commands are usage errors.

Terminal
bash
elide --limit=workers=4 --limit=fds=128 --max-mem=512m --timeout=30s run app.js

Workers inherit their parent’s grants. These flags do not isolate the process from a native crash.

Pick a profile

--sandbox=trusted is the default profile. --sandbox=sandboxed and --sandbox=isolated are unavailable and exit with code 2.

Flags

Flag Effect
--sandbox Deny filesystem access and subprocesses. The network stays allowed.
--allow-read[=PATHS] Allow reads everywhere, or at the listed paths. Implies --sandbox.
--allow-write[=PATHS] Allow writes everywhere, or at the listed paths. Implies --sandbox.
--fs-audit Log each filesystem decision to stderr.
--allow-net[=HOSTS] Allow all network access, or only the listed hosts (HOST or HOST:PORT).
--allow-run[=CMDS] Allow all subprocesses, or only the listed commands. Needed under --sandbox.
--deny-net=HOSTS Deny hosts even when allowed.
--deny-run=CMDS Deny commands even when allowed.
--allow-env[=NAMES] Pass the listed host environment variables, or all of them, to Python’s os.environ, and let elide.pkl read them. process.env is unchanged.
--allow-threads Allow Python threads in a sandbox.
--allow-native Allow native access (the default).
--no-native Deny native access.
--limit=workers=N Limit live workers; exceeding it throws ERR_WORKER_LIMIT.
--limit=fds=N Limit open node:fs handles; exceeding it throws EMFILE.
--max-mem=SIZE Limit the heap size; exceeding it is an out-of-memory error with a nonzero exit.
--timeout=DURATION Stop the program after DURATION with exit 124.

Lists are comma-separated. --deny-net and --deny-run need the = form.

An elide.pkl or package.json script, or a node_modules/.bin command, run with elide run NAME is a host command and cannot be sandboxed. With --sandbox, --allow-read, --allow-write, --allow-net, --allow-run, --deny-net, --deny-run or --no-native it exits with code 2.

Samples

Was this page helpful?