Docker & Podman Sandbox

Hardened container execution, resource limits, and network isolation.

NIKI’s default container backend uses Podman or Docker. Unless DOCKER_HOST overrides discovery, it probes the rootless Podman socket before rootful Podman and Docker sockets; rootless execution is not guaranteed.

Configuration ([docker])

Control memory quotas, CPU limits, capabilities, and network behavior in niki.toml:

[docker]
backend          = "docker"              # "docker" (container) or "worktree" (host-local processes)
base_image       = "niki-sandbox:24.04"  # base image
memory_limit     = "2g"                  # memory limit
cpu_limit        = 2.0                   # max CPU cores
pids_limit       = 512                   # max child processes (fork bomb guard)
cap_drop_all     = true                  # drops all Linux capabilities
network_disabled = true                  # blocks all outbound network traffic
readonly_rootfs  = false                 # false leaves the root filesystem writable
extra_packages   = ["nodejs", "npm", "python3"]

Network Egress Control

By default, network_disabled = true gives the container no network. Egress is all-or-nothing: per-domain allowlists are not implemented.

[docker]
network_disabled = false # wildcard-open egress

network_allowlist = ["*"] (or ["all"]) is equivalent. With the default network_disabled = true, a non-wildcard domain list such as ["registry.npmjs.org"] warns and still behaves as block-all; it does not provide selective egress.

Remote Daemon (Cloud-Adjacent Execution)

NIKI honors DOCKER_HOST when connecting to the container runtime. A remote daemon can run the container only if it can access the same project path used in the bind mount:

export DOCKER_HOST="ssh://user@build-host"
niki run "Migrate the test suite to vitest" --project ./my-app

Requirements and honest limits:

• The remote daemon must already have the sandbox image (niki-sandbox:24.04 or your configured base_image); NIKI pulls it on demand where the daemon allows, but a private registry needs its own auth setup.
• The project is bind-mounted by path, not uploaded as build context. The remote host must expose that path with compatible ownership and permissions; treat it with the same trust you give your own machine.
• Prefer SSH with key auth; unencrypted tcp:// daemons expose root-equivalent API access to anyone on the path. NIKI never downgrades this for you.
• niki doctor checks the local toolchain; remote image presence surfaces as a mid-run error, not a doctor failure (yet).

A managed NIKI cloud (hosted runners, no daemon of your own) remains roadmap, not a feature: this page documents what works today.