Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deeplethe/forkd/llms.txt

Use this file to discover all available pages before exploring further.

Every child microVM that forkd forks runs a lightweight TCP agent (forkd-agent.py) on port 8888 inside the guest. The three commands on this page communicate with that agent to execute code, evaluate expressions, and verify the sandbox is alive — without requiring SSH or any additional guest configuration. By default, all three commands connect directly to 10.42.0.2:8888 (the standard guest IP assigned by NetworkConfig::default_tap()). When using per-child network namespaces (--per-child-netns), each child has a forkd-child-<i> netns and the same guest IP is reachable inside it. Pass --child <netns> to enter the correct namespace before dialing.
--child uses setns(2) to enter a network namespace, which requires root or CAP_SYS_ADMIN. When running without root, omit --child and connect directly to a child-specific IP/port if your networking setup exposes them.

​
forkd exec

Run a command inside a live sandbox via the guest agent’s exec endpoint. The command runs as a subprocess inside the guest, and stdout and stderr are streamed back to the caller. The process exit code is propagated as the CLI exit code.
​
--target
string
default:"10.42.0.2:8888"
Address of the guest agent TCP listener. The default matches NetworkConfig::default_tap() — the IP assigned to the guest when the host tap is forkd-tap0 with a 10.42.0.1/24 host address.
​
--child
string
Network namespace name to enter before connecting (e.g. forkd-child-3). Passes setns(2) into /var/run/netns/<name>. Requires root or CAP_SYS_ADMIN. When omitted, connects directly to --target in the current network namespace.
​
--timeout-secs
u64
default:"30"
Command timeout in seconds. If the guest does not return a response within this window, the connection is closed and an error is returned.
​
cmd
string[]
Command and arguments to execute inside the guest, passed after --. Required.
Examples: 
# Execute a Python expression in a specific child namespace
sudo forkd exec --child forkd-child-3 -- python3 -c "import numpy; print(numpy.zeros(3))"
# [0. 0. 0.]

# Run a shell command
sudo forkd exec --child forkd-child-1 -- bash -c "uname -r && whoami"

# Check installed packages inside a sandbox
sudo forkd exec --child forkd-child-5 -- pip list

# Run with a longer timeout for a slow operation
sudo forkd exec --child forkd-child-2 --timeout-secs 120 -- pip install pandas

# Connect directly without namespace (single-child setup without per-child netns)
forkd exec --target 10.42.0.2:8888 -- python3 -c "print('hello')"

​
forkd eval

Evaluate a Python expression against the warmed PID-1 interpreter inside the sandbox. Unlike forkd exec (which spawns a new subprocess that must re-import all packages), eval reuses the already-running Python process that was warm at snapshot time. This makes the difference between 1 ms and 96 ms for a numpy expression.
CallTypical timeWhat it does
forkd eval -- "numpy.zeros(5).sum()"~1 msReuses warmed PID-1 Python; no subprocess, no import
forkd exec -- python3 -c "import numpy; numpy.zeros(5).sum()"~96 msCold subprocess; re-imports numpy from disk
The expression is passed to the agent’s eval endpoint, which calls Python’s eval() in the guest’s __main__ namespace (where all warmup imports are already present). The result is returned as a string (repr() for Python agents) or as JSON (result_json for node-bridge agents). Errors include the traceback.
​
--target
string
default:"10.42.0.2:8888"
Address of the guest agent TCP listener.
​
--child
string
Network namespace name to enter before connecting (e.g. forkd-child-3). Requires root or CAP_SYS_ADMIN.
​
code
string[]
Python expression to evaluate, passed after --. Multiple tokens are joined with a space.
Examples: 
# Evaluate a numpy expression (reuses warmed PID-1 interpreter)
sudo forkd eval --child forkd-child-3 -- "numpy.zeros(5).sum()"
# 0.0

# Evaluate an expression involving a pre-imported library
sudo forkd eval --child forkd-child-1 -- "numpy.zeros(5).tolist()"
# [0.0, 0.0, 0.0, 0.0, 0.0]

# Call a function defined in the warm namespace
sudo forkd eval --child forkd-child-2 -- "len(sys.path)"
# 7

# Without namespace (direct connection)
forkd eval --target 10.42.0.2:8888 -- "1 + 1"
# 2
forkd eval only works when the snapshot was baked with a Python-agent init script (/forkd-init.sh + /forkd-agent.py). Snapshots built with forkd from-image and forkd parent build automatically include these files. The expression runs in __main__ namespace — any names imported at PID-1 startup are available directly.

​
forkd ping

Ping the in-guest TCP agent to verify it is up and responsive. Returns the agent’s JSON pong response, which includes the Python version, a sample library version (if the agent was baked with one), and the PID of the responding process.
​
--target
string
default:"10.42.0.2:8888"
Address of the guest agent TCP listener.
​
--child
string
Network namespace name to enter before connecting (e.g. forkd-child-3). Requires root or CAP_SYS_ADMIN.
Example output: 
sudo forkd ping --child forkd-child-3

{
  "pong": true,
  "numpy_version": "1.26.4",
  "pid": 1
}
The pid: 1 field confirms that the response came from the warm PID-1 interpreter rather than a spawned subprocess — this is the same process that forkd eval sends expressions to. Examples: 
# Ping a specific child namespace
sudo forkd ping --child forkd-child-3

# Ping the default target directly (no namespace)
forkd ping --target 10.42.0.2:8888

# Use in a shell health-check loop
for i in $(seq 1 5); do
  echo -n "child-$i: "
  sudo forkd ping --child "forkd-child-$i" | python3 -c "import sys,json; d=json.load(sys.stdin); print('ok pid=' + str(d['pid']))"
done
forkd snapshot-diff uses an internal equivalent of forkd ping (via POST /v1/sandboxes/:id/ping on the daemon) to wait for the guest agent to come up before running the installer command. The CLI forkd ping is the direct equivalent for interactively verifying a running child.

Build docs developers (and LLMs) love

Get started for freeTalk to us