Services and ports

Long-running services are useful for preview servers, API sandboxes, browser targets, and test dependencies.

Start a service

cargo run -- up servicebox --flake .
cargo run -- exec servicebox -- python -m http.server 8000

Expose a host port only when the workflow needs it:

cargo run -- forward servicebox 8080:8000

The exact command surface may vary by backend and profile; check CLI Commands for current flags.

Security checklist

• Bind only the ports you need.
• Prefer loopback host exposure for local development.
• Do not expose admin consoles without auth.
• Log port-forward creation and teardown.
• Stop or cold-pause the sandbox when the service no longer needs CPU.

Planned runtime SDK shape

Status: Planned lifecycle API.

Python

sandbox = Sandbox.create(image="nix:./flake#service")
proc = sandbox.exec_background(["python", "-m", "http.server", "8000"])
port = sandbox.ports.forward(guest=8000, host=8080)

TypeScript

const sandbox = await Sandbox.create({ image: "nix:./flake#service" });
const proc = await sandbox.execBackground(["node", "server.js"]);
const port = await sandbox.ports.forward({ guest: 8000, host: 8080 });