Programs run unrestricted until you pass a sandbox flag. --sandbox denies filesystem access and subprocesses; the
network stays allowed until you list hosts:
elide --sandbox --allow-read=. --allow-net=example.com run app.js
~/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 serveof a directory, which serves its files from the hostelide java,javac,kotlinc,jar,native-imageand the other JVM and native tools- every other subcommand, such as
build,test,format,install,uv,dev,mcpandrepl, and a bareelidethat 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
@fileargument list or an--env-file - writing diagnostics:
--heap-dump,--jfr,--jitdump,--coverage, and engine options set with-Dor--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
elide --allow-read=. --fs-audit run app.js
[elide.fs] allow read open hello.txt
[elide.fs] DENY write open out.txt
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
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:
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
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 |
# threads.py
import threading
out = []
t = threading.Thread(target=lambda: out.append("worker ran"))
t.start(); t.join()
print(out[0])
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
javaoruv, a project run (elide runwith 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-fileand--project- flags that write files, listen or connect on the host, such as
--heap-dump,--jfr,--jitdump,--coverage,--debugger,--otel-endpoint,--redirect-warningsand-D/-Xengine options - a grant the parent lacks such as
--allow-read, and a different--sandboxprofile
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:
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.
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.