Program Sandbox
Section titled “Program Sandbox”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.
# Register web-app with a read-only root and one writable data directoryhoody 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 /rootimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const computerClient = await client.withComputer({ id: COMPUTER_ID, project_id: PROJECT_ID, server: SERVER });
await computerClient.daemon.programs.create({ name: 'web-app', command: '/usr/bin/node /hoody/storage/apps/web-app/server.js', user: 'web', directory: '/hoody/storage/apps/web-app', port_range: { start: 8080, end: 8080 }, sandbox: { filesystem: { read_only_root: true, writable: ['/hoody/storage/apps/web-app/data'], hidden: ['/root'] }, },});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": "web-app", "command": "/usr/bin/node /hoody/storage/apps/web-app/server.js", "user": "web", "directory": "/hoody/storage/apps/web-app", "port_range": { "start": 8080, "end": 8080 }, "sandbox": { "filesystem": { "read_only_root": true, "writable": ["/hoody/storage/apps/web-app/data"], "hidden": ["/root"] } } }'Registers the program with a read-only root and one writable data directory. The writable directory must already exist.
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":"web-app","command":"/usr/bin/node%20/hoody/storage/apps/web-app/server.js","user":"web","directory":"/hoody/storage/apps/web-app","port_range":{"start":8080,"end":8080},"sandbox":{"filesystem":{"read_only_root":true,"writable":["/hoody/storage/apps/web-app/data"],"hidden":["/root"]}}}&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
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, noterminal_id, and must be persistent: quick-start refuses a sandbox. - Prepare first. The account, working directory, application files and
writabledirectories must exist, with suitable permissions. - Check support. The
sandboxobject ofhoody 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.
Lock down the filesystem
Section titled “Lock down the filesystem”| Field | Effect |
|---|---|
read_only_root: true | The root tree becomes read-only, except a few separate mounts such as /dev, hidden directories, and a private /tmp when private_tmp is on. |
writable | Directories that stay writable. Needs read_only_root; on its own it is a 400. |
hidden | Directories 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.
Limit network ports
Section titled “Limit network ports”mode | The program can |
|---|---|
full (default) | bind and connect anywhere |
restricted | bind only bind_ports and connect only to TCP destination ports in connect_ports, on any host |
none | use 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:
# Register a worker limited to TCP destination ports 5432 and 53hoody 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 64await computerClient.daemon.programs.create({ name: 'queue-worker', command: '/usr/bin/python3 /hoody/storage/apps/worker/main.py', user: 'worker', directory: '/hoody/storage/apps/worker', sandbox: { network: { mode: 'restricted', bind_ports: [9100], connect_ports: [5432, 53] }, process: { max_memory: '256M', max_pids: 64 }, },});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": "queue-worker", "command": "/usr/bin/python3 /hoody/storage/apps/worker/main.py", "user": "worker", "directory": "/hoody/storage/apps/worker", "sandbox": { "network": { "mode": "restricted", "bind_ports": [9100], "connect_ports": [5432, 53] }, "process": { "max_memory": "256M", "max_pids": 64 } } }'Registers a worker that can bind TCP port 9100 and connect only to TCP destination ports 5432 and 53.
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":"queue-worker","command":"/usr/bin/python3%20/hoody/storage/apps/worker/main.py","user":"worker","directory":"/hoody/storage/apps/worker","sandbox":{"network":{"mode":"restricted","bind_ports":[9100],"connect_ports":[5432,53]},"process":{"max_memory":"256M","max_pids":64}}}&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
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.
Choose who can connect
Section titled “Choose who can connect”Ingress rules filter new IPv4 TCP connections from the network to the program’s listening set. Established connections are never cut.
| Field | Effect |
|---|---|
ingress_allow_from | Up 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_platform | Default 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.
# 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// The object replaces the stored block; the SDK does not check what it drops.await computerClient.daemon.programs.update(programId, { sandbox: { filesystem: { read_only_root: true, writable: ['/hoody/storage/apps/web-app/data'], hidden: ['/root'] }, network: { bind_ports: [8080], ingress_allow_from: ['203.0.113.0/24'], ingress_allow_platform: true, ingress_rate_limit: '50/s', }, },});curl -X POST "https://$PROJECT_ID-$COMPUTER_ID-daemon-1.$SERVER.computers.hoody.com/api/v1/daemon/programs/edit/$PROGRAM_ID" \ -H "Content-Type: application/json" \ -d '{ "sandbox": { "filesystem": { "read_only_root": true, "writable": ["/hoody/storage/apps/web-app/data"], "hidden": ["/root"] }, "network": { "bind_ports": [8080], "ingress_allow_from": ["203.0.113.0/24"], "ingress_allow_platform": true, "ingress_rate_limit": "50/s" } } }'Replaces the sandbox block: the running instance stops, and a boot program returns under the new policy. Replace PROGRAM_ID and the example network 203.0.113.0/24.
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/edit/PROGRAM_ID&method=POST&json={"sandbox":{"filesystem":{"read_only_root":true,"writable":["/hoody/storage/apps/web-app/data"],"hidden":["/root"]},"network":{"bind_ports":[8080],"ingress_allow_from":["203.0.113.0/24"],"ingress_allow_platform":true,"ingress_rate_limit":"50/s"}}}&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
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.
Cap memory, CPU and processes
Section titled “Cap memory, CPU and processes”| Field | Limits |
|---|---|
max_memory | memory of the program and its processes, 16M to 64G, no swap |
max_cpu | CPU, where "100%" is one CPU |
max_pids | processes and threads; the sandbox uses 2 |
max_open_files, max_file_size | open files, and the size of any one file |
private_tmp, tmp_size | its 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:
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 256Mawait computerClient.daemon.programs.create({ name: 'batch-job', command: '/usr/bin/python3 /hoody/storage/apps/batch/run.py', user: 'worker', directory: '/hoody/storage/apps/batch', sandbox: { network: { udp: 'deny' }, process: { max_cpu: '50%', max_memory: '1G', max_file_size: '2G', private_tmp: true, tmp_size: '256M' }, },});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": "batch-job", "command": "/usr/bin/python3 /hoody/storage/apps/batch/run.py", "user": "worker", "directory": "/hoody/storage/apps/batch", "sandbox": { "network": { "udp": "deny" }, "process": { "max_cpu": "50%", "max_memory": "1G", "max_file_size": "2G", "private_tmp": true, "tmp_size": "256M" } } }'Registers a batch job with CPU, memory, file-size and temporary-space limits and no UDP.
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":"batch-job","command":"/usr/bin/python3%20/hoody/storage/apps/batch/run.py","user":"worker","directory":"/hoody/storage/apps/batch","sandbox":{"network":{"udp":"deny"},"process":{"max_cpu":"50%25","max_memory":"1G","max_file_size":"2G","private_tmp":true,"tmp_size":"256M"}}}&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
Its private /tmp and /var/tmp hold 256 MiB each, counted against max_memory.
Change or remove a sandbox
Section titled “Change or remove a sandbox”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.
# Clear the block, then read back what the daemon still holdshoody daemon programs update "$PROGRAM_ID" -c "$COMPUTER_ID" --sandbox nullhoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"await computerClient.daemon.programs.update(programId, { sandbox: null });const { data } = await computerClient.daemon.programs.getSandbox(programId);console.log(data.firewall, data.problems);curl -X POST "https://$PROJECT_ID-$COMPUTER_ID-daemon-1.$SERVER.computers.hoody.com/api/v1/daemon/programs/edit/$PROGRAM_ID" \ -H "Content-Type: application/json" -d '{"sandbox": null}'Clears the program’s sandbox. Replace PROGRAM_ID.
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/edit/PROGRAM_ID&method=POST&json={"sandbox":null}&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
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.
What changes for a sandboxed program
Section titled “What changes for a sandboxed program”- Status: the reported
pidis the sandbox’s own process. - Exit codes: a signal death is
128+n, so aSIGKILL, out-of-memory kills included, is 137. A refused launch exits 78 and printssandbox: <reason>in its stderr log. - Environment: values must be literal: no quote of either kind,
%,\or control character. Names such asLD_PRELOADandTMPDIRare a 400. Environment rules has the list. - Isolation: no capabilities, no new privileges,
/sysread-only, and its own System V shared memory and message queues.
Check that a sandbox is working
Section titled “Check that a sandbox is working”# Read the stored policy, its argument vectors and the live firewall statehoody daemon programs sandbox get "$PROGRAM_ID" -c "$COMPUTER_ID"const state = await computerClient.daemon.programs.getSandbox(programId);curl "https://$PROJECT_ID-$COMPUTER_ID-daemon-1.$SERVER.computers.hoody.com/api/v1/daemon/programs/$PROGRAM_ID/sandbox"Reads the stored policy, the argument vectors it resolves to, and the installed ingress rules for one program.
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/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
firewall | Meaning |
|---|---|
ok | The current ingress rules are installed and match. |
draining | Rules of an older policy remain until its processes are confirmed stopped. |
degraded | Something is wrong; problems names it. |
none | This 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.
What the sandbox does not do
Section titled “What the sandbox does not do”- It restricts writes, not reads, and the program still sees the computer’s process list.
- It filters ports, not hosts.
restrictedallows 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,
noneincluded, and a socket listening without binding escapesrestricted. - 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_sizecaps 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.
Advanced
Section titled “Advanced”- 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.
Reference
Section titled “Reference”The Program Sandbox reference holds every field, limit and error, plus troubleshooting.