Program Sandbox reference
Section titled “Program Sandbox reference”Lookup tables for the Program Sandbox; routes are in the management API.
Filesystem fields
Section titled “Filesystem fields”| Field | Accepts | Default | Effect |
|---|---|---|---|
read_only_root | boolean | false | Root tree read-only, except the process information directory (a program can still change its own per-process settings), a fresh /dev, hidden directories, and a private /tmp and /var/tmp when private_tmp is on. /sys is read-only in every sandbox. Account permissions still apply. |
writable | absolute directories | none | Bound read-write. A non-empty list needs read_only_root. |
hidden | absolute directories | none | Replaced by an empty, unreadable directory. Also may not overlap /usr, /bin, /sbin, /lib, /lib64, /lib32, /libx32, /hoody, /hoody/storage, the program’s directory or a writable entry. |
An empty or null list is inert. /run/user is hidden in every sandbox, even a runtime directory created later, so systemctl --user and a session bus under that path are out of reach. A bus reachable another way can stay reachable (limitations). A directory under /run/user is a 400.
Path rules
Section titled “Path rules”- Shape: an existing absolute directory, no
.., only ASCII letters, digits,/,_,.,-, space and tab. Canonicalized;/is forbidden. - Protected roots: a path may not equal, contain or lie inside the daemon’s storage and configuration trees, the log base directory,
/etc,/run,/var/run,/hoody/plugins, the process information directory,/sys,/dev,/bootor the daemon executable’s directory. So/hoodyand/hoody/storageare refused;/hoody/storage/apps/my-apiworks aswritable. - At launch: each path is checked again; one that changed identity or is no longer a directory is refused. The identity seen when stored is not pinned. The directory made writable is the one checked.
- Renames: where a directory appears is resolved by path and never rechecked while running. Anyone who can rename a validated directory, or one above it, can move where a hidden directory lands, exposing its contents under the new name. It can also move where a writable directory appears. Neither reaches anything the account could not otherwise reach. Do not rely on
hiddenwhere untrusted code can rename those directories.
Network fields
Section titled “Network fields”| Field | Accepts | Default | Effect |
|---|---|---|---|
mode | full, restricted, none | full | full: no bind or connect limit; ingress settings still apply. restricted: TCP bind and connect only to the lists below. none: isolated network namespace; cannot reach the computer’s IP network or abstract Unix sockets outside the sandbox. Socket creation is still possible, and Unix sockets by path remain reachable. |
bind_ports | ports, "a-b" ranges | port_range plus ready_port | TCP ports it may bind under restricted; also the listening set for ingress and port ownership. An explicit [] gets no defaults. |
connect_ports | ports, ranges | none | TCP destination ports, any host. Only with restricted, where [] denies every connect. |
ingress_allow_from | up to 64 CIDRs | none | Strict IPv4 a.b.c.d/n, prefix 0 to 32 in plain decimal (/24; /024 and /+24 are refused). Empty or omitted: no source restriction. |
ingress_allow_platform | boolean | true | Incoming traffic from the gateway or a source in 127.0.0.0/8 skips the rate limit and allowlist. Setting false removes those exemptions; local loopback connections remain outside these rules. If no default gateway is found, the first host of the first connected network on eth0 is used when available. |
ingress_rate_limit | "N/s", "N/m", N 1 to 100000 | none | Per-source budget of connection-opening packets, ECN-capable included, with a burst of N. Not a fixed window. |
udp | allow, deny | allow | deny in any mode: UDP sockets fail with EACCES, ICMP ping and SCTP sockets are refused, and io_uring is unavailable. |
Both ingress fields need a non-empty listening set.
No network at all
Section titled “No network at all”mode: none suits an offline worker. Declare no ports with it:
- In the Hub, pick the computer and open Programs under its name.
- Choose New program and Keep it under How it runs.
- Set Name to
offline-worker, Command to/usr/bin/python3 /hoody/storage/apps/worker/main.pyand Run as toworker, and select No port under Ports. - Under Advanced, set Working folder to
/hoody/storage/apps/worker. - Open Limit what this program can do, turn on Make files read-only, set Connections to None and select Own temporary folder.
- Select Add program.
hoody daemon programs create -c "$COMPUTER_ID" \ --name offline-worker \ --command "/usr/bin/python3 /hoody/storage/apps/worker/main.py" \ --user worker \ --cwd /hoody/storage/apps/worker \ --sandbox-filesystem-read-only-root \ --sandbox-network-mode none \ --sandbox-process-private-tmpawait computerClient.daemon.programs.create({ name: 'offline-worker', command: '/usr/bin/python3 /hoody/storage/apps/worker/main.py', user: 'worker', directory: '/hoody/storage/apps/worker', sandbox: { filesystem: { read_only_root: true }, network: { mode: 'none' }, process: { private_tmp: true }, },});curl -X POST "https://$PROJECT_ID-$COMPUTER_ID-daemon-1.$SERVER.computers.hoody.com/api/v1/daemon/programs/add" \ -H "Content-Type: application/json" \ -d '{ "name": "offline-worker", "command": "/usr/bin/python3 /hoody/storage/apps/worker/main.py", "user": "worker", "directory": "/hoody/storage/apps/worker", "sandbox": { "filesystem": { "read_only_root": true }, "network": { "mode": "none" }, "process": { "private_tmp": true } } }'Registers a worker with no network, a read-only root and its own temporary directories.
https://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-daemon-1.SERVER.computers.hoody.com/api/v1/daemon/programs/add&method=POST&json={"name":"offline-worker","command":"/usr/bin/python3%20/hoody/storage/apps/worker/main.py","user":"worker","directory":"/hoody/storage/apps/worker","sandbox":{"filesystem":{"read_only_root":true},"network":{"mode":"none"},"process":{"private_tmp":true}}}&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
Unix sockets by path and readable files outside hidden directories stay reachable.
Port rules
Section titled “Port rules”- Items: 1 to 65535, or
"a-b"with1 <= a <= b <= 65535. Overlapping or adjacent items merge. - Coverage:
bind_portsmust coverport_rangeandready_port. With neither,restrictedrequiresbind_ports. none: refusesport_range,ready_port, any non-nullbind_ports([]included), non-emptyconnect_portsoringress_allow_from, and a rate limit.- Reserved: Hoody Kit ports
4,5,44,45,46,48,50,55,59,60,61,75,76,77,78,3971,3998,3999,4000,23333and the daemon’s own port. - Old spellings: an older daemon’s record with
/024reads as/24, but correct the stored block with an edit. An unreadable allowlist entry makes the firewall state fail to load.
What the network policy leaves open
Section titled “What the network policy leaves open”- Listening without binding: outside
restricted; ingress covers it only on a declared port. - Unix sockets: abstract ones are reachable under
fullandrestricted. Ones reachable by path stay reachable in every mode, so undernonethe filesystem policy decides. restrictedrefusals: MPTCP answersEPROTONOSUPPORT, SMC is refused,io_uring_setupanswersENOSYS, aMSG_FASTOPENsend answersEOPNOTSUPP. Fallbacks to plain TCP, epoll or connect-then-send work; software requiring io_uring does not. A running program gets this at its next start.- 32-bit x86: the legacy
socketcallinterface cannot create sockets (Unix included) or send underrestricted, or create any socket underudp: "deny". Itssocketpairand the direct calls work. - Errors: a denied bind or connect fails with
EACCES(Permission denied) in every child. Ingress silently drops: a refused source times out, and a rate-limited one can succeed on retry. - Passed-in sockets: a socket or io_uring ring created outside and passed in over a Unix socket is not covered.
Name lookups with udp: "deny"
Section titled “Name lookups with udp: "deny"”- The glibc resolver switches to TCP. Under
restricted, add port 53 toconnect_ports. - Another resolver or C library needs DNS over TCP configured.
- Except under
none, the launch is refused when/etc/resolv.confis unreadable, not a regular file, over 64 KiB, or resolves into a hidden, writable or private temporary path,/run/useror/dev.
Ingress rules
Section titled “Ingress rules”- Scope: new IPv4 TCP connections arriving on
eth0, matched by destination port, never destination address. An undeclared service on a matching port is filtered too. Traffic arriving through other interfaces is not covered. - Order: established packets pass, invalid ones drop, then exemption, rate limit, allowlist; the rest drops. A rate-limit-only policy drops nothing within the limit.
- Exemption: by source address. A computer calling a public service URL on its own server arrives from the server’s public address, so it is not exempt.
- Rate limit: counts attempts, not requests or bytes, one budget per source across every port and instance of a revision. Up to 65535 sources, each for 60 seconds; beyond that new sources pass, and the allowlist still applies.
- Resets: budgets reset when rules are rebuilt: an ingress policy added, retired, finished or rolled back, a lazy start that completes a drain, and every daemon start and reset. An identical policy usually leaves matching rules unchanged, but a rebuild can still occur and reset the budgets.
Port ownership
Section titled “Port ownership”- An effective block’s listening set is reserved on every local address. Overlapping another program’s declared ports or a draining policy is a 400 when a sandbox is on either side.
- Two unsandboxed programs keep the older rule: overlapping
port_rangevalues are refused, disabled programs included;ready_portis not checked. - A port a firewall record holds is refused to everyone. Disable and remove keep ports while a record is active or draining; a failed release is logged and reconciled at the next daemon start.
- An add reusing a removed program’s
idis checked against its records. A disabled program with no records left stops conflicting. - Enabling re-checks ownership, so a port taken meanwhile refuses the enable.
- Undeclared ports cannot be reserved.
- Ownership is checked by the API and at daemon start, not when one program is applied or launched.
Process fields
Section titled “Process fields”| Field | Accepts | Effect |
|---|---|---|
max_memory | 16M to 64G | Program and its processes. No swap. |
max_pids | 4 to 65536 | Processes and threads. The sandbox uses 2. |
max_open_files | 8 to 1048576 | Soft and hard limit, set just before start, so the sandbox’s files do not count. |
max_cpu | "<n>%", 1 to 102400 | Against one CPU: "200%" is two. Per instance for a port range. |
max_file_size | 1K to 1024G | Largest single file. Past it, a write fails with EFBIG (File too large), usually without a kill. Log files are not covered. |
private_tmp | boolean, false | Own empty /tmp and /var/tmp. |
tmp_size | 1M to 64G | Each private directory, so twice that together. A 400 without private_tmp: true. In memory, counted in max_memory; past it, ENOSPC. Without it, each private directory takes the kernel’s default tmpfs size, half of RAM. |
- Sizes:
<n>[KMG]in binary units, or a decimal byte count such as"16777216". No limit has a default. private_tmp400s: awritablepath that equals, contains or lies inside/tmpor/var/tmp; adirectorystrictly below either; a daemon installed at or below either.- Out of memory: the kernel kills one process, not necessarily the one asking. If it is the program, it exits 137 and the rest are stopped.
/sysread-only: the program cannot raise its limits.
Effective blocks and edits
Section titled “Effective blocks and edits”- Effective: at least one of
read_only_root, a non-emptyhidden,modeother thanfull, a non-emptyingress_allow_from,ingress_rate_limit,udp: "deny",max_memory,max_pids,max_cpu,max_open_files,max_file_sizeorprivate_tmp. Otherwise the block is stored as absent and claims no ports. - Stored as sent: not expanded into defaults; null fields may be omitted when read back. A no-op block survives only in a hand-edited program file.
- Edits: an edit validates the merged program, so omitting
sandboxdoes not skip the checks on a stored block. - Strict keys: an unknown key at any level is a 400, including a newer client’s field on an older daemon.
private_pid,no_new_privilegesand capability grants are unsupported. - Size: a resolved policy over 64 KiB is refused with
sandbox policy is too large. - CLI guard: a stored
falsecounts as a setting; nulls and empty lists do not. A failed read refuses the edit.--sandbox nullclears without the check. It does not judge weaker values. - Revision: a 12-hex
rev. Reorderingbind_portsorconnect_portskeeps it; reorderingwritable,hiddenoringress_allow_fromchanges it. - Reload: a new revision stops the old instance; a
bootprogram comes back. An unchanged rendered program configuration skips the reload unless an earlier apply is unconfirmed. Command or environment changes can reload the program even when its sandbox policy is unchanged. A disabled program’s configuration is removed instead.
Environment
Section titled “Environment”- Literal values:
%, either quote, a backslash, a control character, or whitespace followed by;or#causes a 400 inenvironment. Unsafe injected or referenced values are dropped. The process manager would otherwise expand (%(...)s,%(...)c), split, cut or unquote it. display: validated the same way.- Refused names:
LD_*,GCONV_PATH,GETCONF_DIR,HOSTALIASES,LOCALDOMAIN,LOCPATH,MALLOC_*,NIS_PATH,NLSPATH,RESOLV_HOST_CONF,RES_OPTIONS,TMPDIR,TZDIR,GLIBC_TUNABLESandHOODY_SANDBOX_*are a 400, and filtered from the injected environment with a warning, though not from the process manager’s own. - Names: C identifiers only.
- Removed: the process manager’s variables, including its control socket address.
- Every program: create and edit reject a
commandcontaining LF, CR or NUL andenvironmentvalues containing LF or CR. Unsandboxed programs follow the ordinary rule. - Secrets:
inject_computer_env: truepasses the computer environment minus the refused names and any value that is not literal (see Environment above). Give untrusted programs no ambient credentials and minimal file permissions.
Launch checks
Section titled “Launch checks”- Refusal:
sandbox: <reason>on stderr, exit 78. A cancelled launch or failed setup prints a diagnostic and exits with a child’s code or 143. - Account and name:
user: rootis a 400 and refused at launch: root stays uid 0 to the system bus and control socket. A name of.or..is refused, even from a hand-edited or restored file. - Stored program: an unreadable program list (another program’s bad entry included), a missing or disabled program, an ineffective block, or
revision mismatch: ... (re-apply the program)exits 78. Use the edit endpoint, not hand edits. - Validation: any stored block is validated when applied, so a broken one never runs unconfined.
- Limits:
max_memorywith its swap cap,max_pidsandmax_cpuare read back. Unreadable, unlimited or different exits 78 withsandbox: the resource limits could not be confirmed, so the program was not started: .... Memory may round down to a page; CPU may differ by 1%. - Ingress: installed rules must match the last applied change, or the launch is refused; so is a check over 5 seconds or a listing over 8 MiB, which grows with rules, not traffic. A change in progress delays the launch.
- Draining: a finished removal or disable refuses the launch; one arriving during it lets the instance start and drain with the old rules.
- Command: a first word with
/is used as written, otherwise searched onPATH, skipping empty entries (write.) and files the user cannot run. Not found:sandbox: inner: ..., exit 78. Scripts need a valid interpreter line.
Sandbox state
Section titled “Sandbox state”GET /api/v1/daemon/programs/{id}/sandbox is read-only: 200 for any program, 404 for an unknown id. Without a valid effective policy, rev and effective are null.
| Field | Meaning |
|---|---|
configured | Stored block, or null. |
rev | First 12 hex digits of the policy’s SHA-256; also in live.chain. |
effective.bwrap_argv | Filesystem-isolation command line, a template: <opened-at-launch> per writable directory, <program argv> for the command. Port limits and max_open_files are absent. |
effective.scope_argv | Process-limit command line with <port> and <pid> placeholders. |
live.table_present | Rules found and read. false also on a failed read. |
live.chain | Expected rule-set name, or null. Not proof it exists. |
live.rules | Current rules as JSON, in evaluation order. |
problems | Invalid stored policy, unreadable firewall state, a policy with no matching record, another revision’s record, changed rules, or an earlier definition possibly running unconfined. |
firewall | ok, degraded, draining or none. |
ok: a matching active record, no drain, rules match the fingerprint.degraded:problemsis non-empty. Allowlists are fingerprinted; rate-limit sources are not. Wins overdraining.draining: a draining record remains, even after the block was cleared.none: nothing owed under any revision. A disabled program with no record still showsconfigured,revandeffective. Other programs may own rules.
Unsandboxed, with no firewall history:
{ "success": true, "configured": null, "rev": null, "effective": null, "live": { "table_present": false, "chain": null, "rules": [] }, "problems": [], "firewall": "none"}Draining
Section titled “Draining”- Old rules and ports stay until the old instances are confirmed stopped, launches finish and the latest configuration is applied, or briefly longer.
- Disable drains the current revision.
- Add and edit return with no firewall field. Poll the sandbox state. A removed program answers 404; its record shows only in daemon logs.
- Detached children of sandboxed runs remain tracked until they stop. Detached processes from earlier unconfined runs are not tracked. If the daemon has never seen inside sandboxes, every revision counts as alive.
- While revisions coexist, a packet to a shared port must pass both allowlists.
Unconfined processes
Section titled “Unconfined processes”When a sandbox cannot be installed, at daemon start or after a failed add, edit, enable or start, the daemon stops any unconfined process under it, best effort: a detached child is unseen, and two programs that shared a name can stop each other’s processes. Until confirmed, its ports stay reserved and problems says why; if that cannot be recorded, a later drain can remove its ingress rules while the listener may still be up, so check the computer yourself. Programs without a sandbox are never stopped this way. Fix the cause, then enable or edit it.
Reinstall ingress rules
Section titled “Reinstall ingress rules”If a tool removed the ingress rules, running programs listen unfiltered. A daemon restart, a committed ingress change or starting the program through the daemon rebuilds them (the start fails if restoration fails); so does disable then enable, which interrupts the program. The start names 8080, the port of the web-app example. Use a port in your program’s range, and repeat the start for each instance; for a program without a port range, omit the port:
# Interrupts the program. Check each response before the next command.hoody daemon programs disable "$PROGRAM_ID" -c "$COMPUTER_ID"hoody daemon programs enable "$PROGRAM_ID" -c "$COMPUTER_ID"hoody daemon programs start "$PROGRAM_ID" -c "$COMPUTER_ID" --port 8080 --if-not-runninghoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"await computerClient.daemon.programs.disable(programId);await computerClient.daemon.programs.enable(programId);await computerClient.daemon.programs.start(programId, { port: 8080, if_not_running: true });const state = await computerClient.daemon.programs.getSandbox(programId);DAEMON_URL="https://$PROJECT_ID-$COMPUTER_ID-daemon-1.$SERVER.computers.hoody.com"
curl -X POST "$DAEMON_URL/api/v1/daemon/programs/$PROGRAM_ID/disable"curl -X POST "$DAEMON_URL/api/v1/daemon/programs/$PROGRAM_ID/enable"curl -X POST "$DAEMON_URL/api/v1/daemon/programs/$PROGRAM_ID/start" \ -H "Content-Type: application/json" -d '{"port": 8080, "if_not_running": true}'curl "$DAEMON_URL/api/v1/daemon/programs/$PROGRAM_ID/sandbox"Open them in order, checking each answer. Replace PROGRAM_ID.
# Disablehttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-daemon-1.SERVER.computers.hoody.com/api/v1/daemon/programs/PROGRAM_ID/disable&method=POST&response=transparent
# Enablehttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-daemon-1.SERVER.computers.hoody.com/api/v1/daemon/programs/PROGRAM_ID/enable&method=POST&response=transparent
# Starthttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-daemon-1.SERVER.computers.hoody.com/api/v1/daemon/programs/PROGRAM_ID/start&method=POST&json={"port":8080,"if_not_running":true}&response=transparent
# Checkhttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-daemon-1.SERVER.computers.hoody.com/api/v1/daemon/programs/PROGRAM_ID/sandbox&method=GET&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
Expect firewall: "ok" after any drain. With the record intact, missing or text-readable saved rules are rewritten too. An edit of an enabled program or a start with the same policy checks the live ingress rules and attempts to rebuild them if they are missing or changed; the operation can fail if the rebuild fails.
Prerequisites
Section titled “Prerequisites”| Needed | For |
|---|---|
bwrap, systemd_run, user namespaces, an existing /run/user | every sandbox |
landlock_abi 4 or higher | mode: restricted |
nft | ingress policies |
a bwrap that can pin directories | writable |
bwrap_tmpfs_size: true | tmp_size |
a readable /etc/resolv.conf | udp: "deny", except under none |
The daemon’s executable and configuration paths must be absolute, using only ASCII letters, digits, /, _, . and -. Setup installs the tools. The sandbox section of health (hoody daemon health) reports bwrap, nft, systemd_run, landlock_abi, bwrap_version, bwrap_tmpfs_size and firewall. It does not report every prerequisite in the table. Health stays 200 with status: "ok". Restart the daemon after installing one. Its firewall is ok when installed rules match the recorded fingerprint, degraded when they differ or it cannot read them or the record. Stored records only: never draining, ok while records drain, none when no record exists, which can hide an error.
Restart recovery
Section titled “Restart recovery”Whenever the computer’s process manager starts, saved ingress rules go back first, so no listener comes up unfiltered. If they cannot, no daemon program runs, Hoody Kit programs included. This needs Python 3 and flock. The record is sandbox-firewall-state.json and the saved rules are sandbox-firewall.nft. Both sit in the directory that holds the daemon’s programs.json, by default /hoody/storage/hoody-daemon/config/. Restore the two together from one backup, and check that the pair holds the policies you want.
| Code | Meaning | Fix |
|---|---|---|
| 2 | Configuration, record or saved rules unreadable | Fix permissions or restore the pair |
| 3 | Rules owed, nft missing | Reinstall it |
| 4 | Record lists active or draining policies, saved rules gone | Restore the pair |
| 5 | Saved rules of another record version, or with no version | Restore a matching pair |
| 6 | Saved rules invalid | Restore a matching pair |
| 7 | Valid rules failed to load | Check firewall support, restart the computer |
| 8 | No record or rules, program list unreadable | Fix or restore the program list |
| 9 | No record or rules, an enabled ingress policy | Restore the pair |
| 10 | Python 3 missing | Install it |
| 11 | Record lost after rules were applied, or saved rules without their record | Restore the pair |
| 12 | State directory or lock unusable, or flock missing | Install flock or fix permissions |
| 13 | Saved rules do not match the record or miss a policy it lists | Restore a matching pair |
- Record lost, rules kept: the daemon refuses to rebuild and skips ingress programs at start.
- Both lost: if a sandboxed program runs, a launch is in progress or rules are installed, or any of these cannot be checked, the daemon refuses; otherwise it warns and starts empty.
- Next daemon start: re-applies unconfirmed changes and every enabled sandboxed program,
boot: falseincluded. If a port was still held after boot, start, edit or re-enable the program.
Errors
Section titled “Errors”| Status | When |
|---|---|
| 400 | user: root, terminal_id, restricted without a listening set, a protected path, an unsafe name, a port owned either way, or id 2147483647. |
400 invalid program body: ... | Bad JSON, a wrong type, an unknown key inside sandbox. A repeated top-level key answers duplicate field "<key>": .... |
| 400, saved | Apply failed for a program that has or had a block; rules kept, the next apply retries. |
500 PERSIST: / INTERNAL: | Save failed, or the firewall state could not be read or applied. See the management API. |
- If newly applied rules cannot be read back, the daemon attempts to restore the previous rules. If restoration fails, programs needing ingress rules cannot start until a firewall change commits successfully.
- If the firewall cannot be restored after a failed save, or an apply times out and its retry fails, programs needing ingress rules are refused until a firewall change commits cleanly. Running programs keep running. Neither health nor the sandbox state shows this, so
okthere does not prove the refusal has lifted. - Remove and disable still remove a program whose release failed. A disabled program’s leftover configuration is not swept: disable again.
- A reset can succeed while ingress programs are skipped at boot.
Limitations
Section titled “Limitations”- Reads are not restricted, some trees cannot be hidden, and the process list is visible.
- A rename can move hidden and writable directories.
- Ports, not hosts: UDP, ICMP, sockets listening without binding and Unix sockets by path are outside
restricted. restrictedrefuses MPTCP, SMC, io_uring and Fast Open sends.udp: "deny"moves DNS to TCP only for glibc.- Ingress covers new IPv4 TCP connections; the rate limit resets and fails open.
- A running program is not re-checked.
- A detached earlier run is not stopped.
- Ownership is not checked at launch.
- Restoring rules needs Python 3 and
flock. - No disk quota or bandwidth limit;
max_cpuis per instance. - Injected environment can carry secrets.
- A
displayprogram can lose sound, its audio socket being under/run/user. - A user manager or session bus reachable through another mount path, a runtime directory elsewhere, or an abstract socket under
fullorrestrictedis not hidden. - Each program needs its own block.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
400 on writable | No read_only_root | Add it or drop writable. |
400 on a /hoody path | Protected root | Use /hoody/storage/apps/<name>. |
400 on restricted | No listening set | Add bind_ports. |
| 400 on a port | Declared elsewhere, or a record holds it | Change the port, or wait for that drain. |
| 400 on a variable | Refused name such as LD_PRELOAD | Remove it. |
| Lookups fail | Port 53 missing, or a non-glibc resolver | Add 53, use DNS over TCP, or keep udp: "allow". |
| Never starts | Missing support | Read the sandbox: stderr line and health. |
degraded | See problems | Fix it, then commit an ingress change, or restart the daemon. |
Stuck draining | Old processes remain | Stop them; fix logged errors. |