Skip to content

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

Hoody.com

Lookup tables for the Program Sandbox; routes are in the management API.

FieldAcceptsDefaultEffect
read_only_rootbooleanfalseRoot 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.
writableabsolute directoriesnoneBound read-write. A non-empty list needs read_only_root.
hiddenabsolute directoriesnoneReplaced 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.

  • 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, /boot or the daemon executable’s directory. So /hoody and /hoody/storage are refused; /hoody/storage/apps/my-api works as writable.
  • 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 hidden where untrusted code can rename those directories.
FieldAcceptsDefaultEffect
modefull, restricted, nonefullfull: 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_portsports, "a-b" rangesport_range plus ready_portTCP ports it may bind under restricted; also the listening set for ingress and port ownership. An explicit [] gets no defaults.
connect_portsports, rangesnoneTCP destination ports, any host. Only with restricted, where [] denies every connect.
ingress_allow_fromup to 64 CIDRsnoneStrict 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_platformbooleantrueIncoming 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 100000nonePer-source budget of connection-opening packets, ECN-capable included, with a burst of N. Not a fixed window.
udpallow, denyallowdeny 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.

mode: none suits an offline worker. Declare no ports with it:

  1. In the Hub, pick the computer and open Programs under its name.
  2. Choose New program and Keep it under How it runs.
  3. Set Name to offline-worker, Command to /usr/bin/python3 /hoody/storage/apps/worker/main.py and Run as to worker, and select No port under Ports.
  4. Under Advanced, set Working folder to /hoody/storage/apps/worker.
  5. Open Limit what this program can do, turn on Make files read-only, set Connections to None and select Own temporary folder.
  6. Select Add program.

Unix sockets by path and readable files outside hidden directories stay reachable.

  • Items: 1 to 65535, or "a-b" with 1 <= a <= b <= 65535. Overlapping or adjacent items merge.
  • Coverage: bind_ports must cover port_range and ready_port. With neither, restricted requires bind_ports.
  • none: refuses port_range, ready_port, any non-null bind_ports ([] included), non-empty connect_ports or ingress_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, 23333 and the daemon’s own port.
  • Old spellings: an older daemon’s record with /024 reads as /24, but correct the stored block with an edit. An unreadable allowlist entry makes the firewall state fail to load.
  • Listening without binding: outside restricted; ingress covers it only on a declared port.
  • Unix sockets: abstract ones are reachable under full and restricted. Ones reachable by path stay reachable in every mode, so under none the filesystem policy decides.
  • restricted refusals: MPTCP answers EPROTONOSUPPORT, SMC is refused, io_uring_setup answers ENOSYS, a MSG_FASTOPEN send answers EOPNOTSUPP. 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 socketcall interface cannot create sockets (Unix included) or send under restricted, or create any socket under udp: "deny". Its socketpair and 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.
  • The glibc resolver switches to TCP. Under restricted, add port 53 to connect_ports.
  • Another resolver or C library needs DNS over TCP configured.
  • Except under none, the launch is refused when /etc/resolv.conf is unreadable, not a regular file, over 64 KiB, or resolves into a hidden, writable or private temporary path, /run/user or /dev.
  • 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.
  • 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_range values are refused, disabled programs included; ready_port is 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 id is 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.
FieldAcceptsEffect
max_memory16M to 64GProgram and its processes. No swap.
max_pids4 to 65536Processes and threads. The sandbox uses 2.
max_open_files8 to 1048576Soft and hard limit, set just before start, so the sandbox’s files do not count.
max_cpu"<n>%", 1 to 102400Against one CPU: "200%" is two. Per instance for a port range.
max_file_size1K to 1024GLargest single file. Past it, a write fails with EFBIG (File too large), usually without a kill. Log files are not covered.
private_tmpboolean, falseOwn empty /tmp and /var/tmp.
tmp_size1M to 64GEach 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_tmp 400s: a writable path that equals, contains or lies inside /tmp or /var/tmp; a directory strictly 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.
  • /sys read-only: the program cannot raise its limits.
  • Effective: at least one of read_only_root, a non-empty hidden, mode other than full, a non-empty ingress_allow_from, ingress_rate_limit, udp: "deny", max_memory, max_pids, max_cpu, max_open_files, max_file_size or private_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 sandbox does 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_privileges and capability grants are unsupported.
  • Size: a resolved policy over 64 KiB is refused with sandbox policy is too large.
  • CLI guard: a stored false counts as a setting; nulls and empty lists do not. A failed read refuses the edit. --sandbox null clears without the check. It does not judge weaker values.
  • Revision: a 12-hex rev. Reordering bind_ports or connect_ports keeps it; reordering writable, hidden or ingress_allow_from changes it.
  • Reload: a new revision stops the old instance; a boot program 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.
  • Literal values: %, either quote, a backslash, a control character, or whitespace followed by ; or # causes a 400 in environment. 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_TUNABLES and HOODY_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 command containing LF, CR or NUL and environment values containing LF or CR. Unsandboxed programs follow the ordinary rule.
  • Secrets: inject_computer_env: true passes 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.
  • 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: root is 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_memory with its swap cap, max_pids and max_cpu are read back. Unreadable, unlimited or different exits 78 with sandbox: 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 on PATH, skipping empty entries (write .) and files the user cannot run. Not found: sandbox: inner: ..., exit 78. Scripts need a valid interpreter line.

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.

FieldMeaning
configuredStored block, or null.
revFirst 12 hex digits of the policy’s SHA-256; also in live.chain.
effective.bwrap_argvFilesystem-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_argvProcess-limit command line with <port> and <pid> placeholders.
live.table_presentRules found and read. false also on a failed read.
live.chainExpected rule-set name, or null. Not proof it exists.
live.rulesCurrent rules as JSON, in evaluation order.
problemsInvalid stored policy, unreadable firewall state, a policy with no matching record, another revision’s record, changed rules, or an earlier definition possibly running unconfined.
firewallok, degraded, draining or none.
  • ok: a matching active record, no drain, rules match the fingerprint.
  • degraded: problems is non-empty. Allowlists are fingerprinted; rate-limit sources are not. Wins over draining.
  • draining: a draining record remains, even after the block was cleared.
  • none: nothing owed under any revision. A disabled program with no record still shows configured, rev and effective. 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"
}
  • 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.

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.

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:

Terminal window
# 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-running
hoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"

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.

NeededFor
bwrap, systemd_run, user namespaces, an existing /run/userevery sandbox
landlock_abi 4 or highermode: restricted
nftingress policies
a bwrap that can pin directorieswritable
bwrap_tmpfs_size: truetmp_size
a readable /etc/resolv.confudp: "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.

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.

CodeMeaningFix
2Configuration, record or saved rules unreadableFix permissions or restore the pair
3Rules owed, nft missingReinstall it
4Record lists active or draining policies, saved rules goneRestore the pair
5Saved rules of another record version, or with no versionRestore a matching pair
6Saved rules invalidRestore a matching pair
7Valid rules failed to loadCheck firewall support, restart the computer
8No record or rules, program list unreadableFix or restore the program list
9No record or rules, an enabled ingress policyRestore the pair
10Python 3 missingInstall it
11Record lost after rules were applied, or saved rules without their recordRestore the pair
12State directory or lock unusable, or flock missingInstall flock or fix permissions
13Saved rules do not match the record or miss a policy it listsRestore 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: false included. If a port was still held after boot, start, edit or re-enable the program.
StatusWhen
400user: 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, savedApply 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 ok there 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.
SymptomCauseFix
400 on writableNo read_only_rootAdd it or drop writable.
400 on a /hoody pathProtected rootUse /hoody/storage/apps/<name>.
400 on restrictedNo listening setAdd bind_ports.
400 on a portDeclared elsewhere, or a record holds itChange the port, or wait for that drain.
400 on a variableRefused name such as LD_PRELOADRemove it.
Lookups failPort 53 missing, or a non-glibc resolverAdd 53, use DNS over TCP, or keep udp: "allow".
Never startsMissing supportRead the sandbox: stderr line and health.
degradedSee problemsFix it, then commit an ingress change, or restart the daemon.
Stuck drainingOld processes remainStop them; fix logged errors.