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.

The forkd controller daemon exposes a JSON/HTTP REST API that lets clients create and manage snapshots, fork sandbox child VMs, execute code inside them, and branch running sandboxes into new snapshots. Every operation that mutates state — forking, branching, deleting — goes through this single endpoint, so all lifecycle events are captured in the daemon’s structured audit log.

​
Base URL

The controller listens on http://127.0.0.1:8889 by default. Pass --listen to the daemon to bind a different address or port: 
forkd-controller --listen 0.0.0.0:9000
The default loopback-only bind (127.0.0.1) is safe for single-tenant developer setups. For any multi-tenant or non-loopback deployment, always supply --token-file as well. Exposing the port without a token allows unauthenticated callers to fork sandboxes and run arbitrary code inside them.
To enable TLS, pass --tls-cert and --tls-key to the daemon. The server switches from plain HTTP to HTTPS; no other change is needed on the client side. 
forkd-controller --tls-cert /etc/forkd/server.crt --tls-key /etc/forkd/server.key

​
Authentication

All routes except /healthz require a bearer token when the daemon is started with --token-file. Include the token in every request: 
Authorization: Bearer <contents-of-token-file>
The token file is read once at daemon startup. Rotating the token requires a daemon restart. The comparison is constant-time to close timing-oracle attacks. Generating a token 
sudo mkdir -p /etc/forkd
sudo bash -c 'head -c 32 /dev/urandom | base64 > /etc/forkd/token'
sudo chmod 600 /etc/forkd/token
Then start the daemon with --token-file /etc/forkd/token. Routes that bypass authentication
RouteReason
GET /healthzLiveness probe — load balancers and Kubernetes readiness probes must reach it without credentials.
The bypass accepts both /healthz and /healthz/ (trailing slash). URI paths are case-sensitive per RFC 3986, so /Healthz and /HEALTHZ still require a valid token.
Running without a token file When --token-file is absent, the daemon accepts requests unauthenticated. This is intentional for local development on a loopback-only bind. Client environment variables The official Python and TypeScript SDKs, as well as the forkd CLI, read these variables automatically:
VariablePurpose
FORKD_URLBase URL of the controller, e.g. http://127.0.0.1:8889
FORKD_TOKENBearer token value (the file contents, not the file path)

​
API versioning

Every URL-breaking change moves to a new /vN prefix. The controller supports the previous major version in parallel for one minor release after the new one ships, giving callers a migration window. The current version is /v1. All snapshot and sandbox endpoints are rooted at /v1/.

​
Status endpoints

​
GET /healthz

Liveness probe. Always returns HTTP 200 and bypasses authentication, so load balancers and Kubernetes probes can check the daemon is up without a credential. Response 
{ "ok": true }

​
GET /version

Returns the daemon’s build version and active API version string. Response 
{ "version": "0.1.0", "api": "v1" }

​
GET /metrics

Prometheus text exposition format. Scrape this endpoint with any standard Prometheus-compatible collector. Stable metric names
MetricTypeDescription
forkd_snapshots_totalgaugeNumber of registered snapshots.
forkd_sandboxes_activegaugeNumber of currently-alive child VMs.
forkd_build_info{version="X.Y.Z"}gauge (always 1)Build version label; use for alert routing and dashboards.
Example scrape output 
curl -H "Authorization: Bearer $FORKD_TOKEN" http://127.0.0.1:8889/metrics
# forkd_snapshots_total 3
# forkd_sandboxes_active 5
# forkd_build_info{version="0.5.2"} 1

​
Error format

Every 4xx and 5xx response carries a JSON body with a single error key: 
{ "error": "human-readable message" }
The message is designed to be actionable — for example, a 409 from DELETE /v1/snapshots/:tag names every blocking dependent snapshot by tag so the caller knows exactly what needs to be resolved.

​
Next steps

Snapshots

Create, inspect, delete, and compact parent VM snapshots.

Sandboxes

Fork children, execute code, eval expressions, and branch live VMs.

Build docs developers (and LLMs) love

Get started for freeTalk to us