Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

A sandbox confines one daemon program, and the kernel enforces each limit you set: what it can write or see, which TCP ports it uses, who can connect to it, and how much memory, CPU and processes it gets. Use one for a program that serves traffic or runs code you do not fully control. You add it as the program’s sandbox field on create or edit.

Terminal window
# Register web-app with a read-only root and one writable data directory
hoody daemon programs create -c "$COMPUTER_ID" \
--name web-app \
--command "/usr/bin/node /hoody/storage/apps/web-app/server.js" \
--user web \
--cwd /hoody/storage/apps/web-app \
--port-range-start 8080 --port-range-end 8080 \
--sandbox-filesystem-read-only-root \
--sandbox-filesystem-writable /hoody/storage/apps/web-app/data \
--sandbox-filesystem-hidden /root

The block has three optional parts, filesystem, network and process, and you can set any one alone. Without boot, the create registers the program without starting it; start it as usual.

  • Not root. The program needs a non-root user, no terminal_id, and must be persistent: quick-start refuses a sandbox.
  • Prepare first. The account, working directory, application files and writable directories must exist, with suitable permissions.
  • Check support. The sandbox object of hoody daemon health (GET /api/v1/daemon/health) must show the support your policy needs.

Replace PROJECT_ID, COMPUTER_ID, SERVER and PROGRAM_ID with yours. Every call goes through Hoody Proxy, so its permissions apply.

In the Hub, pick the computer in the top bar and open Programs. For a new program, press New program, choose Keep it, fill in the form, open Limit what this program can do, set the limits and press Add program. For a program you added, select it, press Add sandbox or Edit sandbox in its Sandbox panel, pick a Start from preset or set Files, Network and Resources by hand, and press Save. System programs’ sandboxes can be viewed but not changed here.

FieldEffect
read_only_root: trueThe root tree becomes read-only, except a few separate mounts such as /dev, hidden directories, and a private /tmp when private_tmp is on.
writableDirectories that stay writable. Needs read_only_root; on its own it is a 400.
hiddenDirectories replaced by an empty, unreadable one.

A read-only root stops writes, not reads: the program still reads every file its account can. Only hidden removes a directory from view, and protected trees such as /etc, /run and /hoody cannot be hidden. Every sandbox also hides /run/user. Path rules lists what each list accepts.

modeThe program can
full (default)bind and connect anywhere
restrictedbind only bind_ports and connect only to TCP destination ports in connect_ports, on any host
noneuse no IP network at all; declare no ports with it

restricted covers TCP only. To stop UDP in any mode, set udp: "deny"; with restricted, add TCP port 53 to connect_ports too, or name lookups fail.

This worker has no port_range, so it must list bind_ports:

Terminal window
# Register a worker limited to TCP destination ports 5432 and 53
hoody daemon programs create -c "$COMPUTER_ID" \
--name queue-worker \
--command "/usr/bin/python3 /hoody/storage/apps/worker/main.py" \
--user worker \
--cwd /hoody/storage/apps/worker \
--sandbox-network-mode restricted \
--sandbox-network-bind-ports 9100 \
--sandbox-network-connect-ports 5432,53 \
--sandbox-process-max-memory 256M \
--sandbox-process-max-pids 64

A denied bind or connect fails with EACCES, in every child process too. The listening set (bind_ports, or port_range and ready_port when you omit it) is reserved computer-wide, so another program cannot declare those ports.

Ingress rules filter new IPv4 TCP connections from the network to the program’s listening set. Established connections are never cut.

FieldEffect
ingress_allow_fromUp to 64 IPv4 CIDRs allowed to connect. Omitted or empty means no source restriction.
ingress_rate_limit"N/s" or "N/m": a budget of new connections per source, checked before the allowlist.
ingress_allow_platformDefault true: the computer’s network gateway skips both checks. Set false to filter and meter it too. Connections from inside the computer itself never pass through these checks, whatever the setting.

The exemption goes by source address. Hoody Proxy forwards public requests with the client’s own address, so they meet the allowlist and rate limit: list the networks your clients come from. A refused source usually sees a timeout.

These commands update web-app, resending its filesystem block because an edit replaces the whole sandbox block.

Terminal window
# Refused, listing each setting, if the stored block has settings this edit drops.
# Add them to the command, or add --sandbox-replace to drop them.
hoody daemon programs update "$PROGRAM_ID" -c "$COMPUTER_ID" \
--sandbox-filesystem-read-only-root \
--sandbox-filesystem-writable /hoody/storage/apps/web-app/data \
--sandbox-filesystem-hidden /root \
--sandbox-network-bind-ports 8080 \
--sandbox-network-ingress-allow-from 203.0.113.0/24 \
--sandbox-network-ingress-allow-platform \
--sandbox-network-ingress-rate-limit 50/s

This accepts connections on port 8080 from one network, metering 50 connection attempts per second per source with a burst of 50. Because it replaces the whole block, the edit resends the filesystem block from the first example; anything you leave out is removed, the network mode returns to full and udp to allow. The computer firewall covers the whole computer instead of one program’s ports.

FieldLimits
max_memorymemory of the program and its processes, 16M to 64G, no swap
max_cpuCPU, where "100%" is one CPU
max_pidsprocesses and threads; the sandbox uses 2
max_open_files, max_file_sizeopen files, and the size of any one file
private_tmp, tmp_sizeits own empty /tmp and /var/tmp, and their size

At max_memory the kernel kills one of the program’s processes; when that is the program, it exits with 137. This batch job gets half a CPU, 1 GiB and no UDP:

Terminal window
hoody daemon programs create -c "$COMPUTER_ID" \
--name batch-job \
--command "/usr/bin/python3 /hoody/storage/apps/batch/run.py" \
--user worker \
--cwd /hoody/storage/apps/batch \
--sandbox-network-udp deny \
--sandbox-process-max-cpu 50% --sandbox-process-max-memory 1G \
--sandbox-process-max-file-size 2G \
--sandbox-process-private-tmp --sandbox-process-tmp-size 256M

Its private /tmp and /var/tmp hold 256 MiB each, counted against max_memory.

On edit, sandbox has three states: absent keeps the block, null clears it, and an object replaces it whole. Fields you leave out are removed, so resend every restriction you want kept. An edit with any --sandbox-* flag is checked by the CLI, which refuses one that drops a stored setting; --sandbox-replace sends it anyway.

In the Hub, open Programs, select a program you added and press Edit sandbox. Change the fields and press Save, or press Remove sandbox and confirm with Remove.

Terminal window
# Clear the block, then read back what the daemon still holds
hoody daemon programs update "$PROGRAM_ID" -c "$COMPUTER_ID" --sandbox null
hoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"

A change to the resolved policy stops the running instance. A boot program comes back; a lazy or non-boot one stays down until started. The old ingress rules stay until its processes are confirmed stopped, so configured: null is not proof they are gone: watch firewall until it reads none. A block that restricts nothing is stored as absent.

  • Status: the reported pid is the sandbox’s own process.
  • Exit codes: a signal death is 128+n, so a SIGKILL, out-of-memory kills included, is 137. A refused launch exits 78 and prints sandbox: <reason> in its stderr log.
  • Environment: values must be literal: no quote of either kind, %, \ or control character. Names such as LD_PRELOAD and TMPDIR are a 400. Environment rules has the list.
  • Isolation: no capabilities, no new privileges, /sys read-only, and its own System V shared memory and message queues.
Terminal window
# Read the stored policy, its argument vectors and the live firewall state
hoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"
firewallMeaning
okThe current ingress rules are installed and match.
drainingRules of an older policy remain until its processes are confirmed stopped.
degradedSomething is wrong; problems names it.
noneThis program owes no ingress rules.

This reports the stored policy and the installed ingress rules; it does not inspect the running process. A sandbox that cannot be set up fails closed: the program never starts. Read its stderr log, then the sandbox object of hoody daemon health.

In the Hub, the program’s Sandbox panel in Programs shows Saved policy, Used at next start and Inbound firewall now, plus What the computer reports when the computer reports a problem.

  • It restricts writes, not reads, and the program still sees the computer’s process list.
  • It filters ports, not hosts. restricted allows its ports to any destination, and ingress rules cover IPv4 TCP only.
  • Some sockets stay open. Unix sockets reachable by path work in every mode, none included, and a socket listening without binding escapes restricted.
  • Hidden directories can move. Anyone who can rename a directory above them can expose their contents under a new name.
  • It does not clean up earlier runs. A detached child of an unsandboxed run keeps running unconfined.
  • It has no disk quota. max_file_size caps one file, not the total written.
  • It does not re-check a running program. If something removes its ingress rules, it keeps listening unfiltered until the rules are rebuilt; starting the program through the daemon also restores them.
  • The rate limit is best effort. Budgets reset when rules are rebuilt, and past 65535 sources new ones are not metered.

The limitations list has the full list.

  • No network at all: mode: none (--sandbox-network-mode none, or "network": {"mode": "none"}) closes IP and abstract Unix sockets. Use it for an offline worker. See the example.
  • Port ownership: a declared port is reserved computer-wide, even against unsandboxed programs, until any drain ends. See port ownership.
  • Draining: after a policy change or disable, old rules and ports stay until old processes stop. Poll the sandbox state to know when. See draining.
  • Reinstall rules: if a tool removed the ingress rules, a disable then enable, a daemon restart, or starting the program through the daemon, rebuilds them. See reinstall ingress rules.
  • Restart recovery: at computer start, saved ingress rules go back first; if they cannot, no daemon program starts. See restart recovery.
  • Launch checks: each launch confirms limits, paths and rules, and resolves the command on the program’s PATH. See launch checks.
  • Diagnostics: the sandbox state also shows the revision rev, the resolved command lines and the installed rules. See sandbox state.

The Program Sandbox reference holds every field, limit and error, plus troubleshooting.