Skip to content

Configuration

bhatti reads YAML from the server config and optional per-user CLI credentials. On a fresh install the API is local-socket only. For transport security and remote access, read Self-hosting; this page enumerates settings.

BHATTI_CONFIG loads only the file named by that variable. Otherwise /etc/bhatti/config.yaml supplies server settings (an older /var/lib/bhatti/config.yaml is a deprecated fallback); ~/.bhatti/config.yaml fills in api_url and auth_token only if still unset. BHATTI_LOG_LEVEL controls daemon logging (debug, info, warn, error).

# ~/.bhatti/config.yaml — written for the invoking user by the installer
# A remote CLI may instead use: api_url: https://api.yourdomain.com
auth_token: bht_...

For the endpoint, CLI precedence is --url → BHATTI_URL → api_url → <data_dir>/api.sock (or configured api_socket), not a built-in TCP fallback. For the key, use --token → BHATTI_TOKEN → auth_token. bhatti version reports the selected endpoint. BHATTI_FORCE_STREAM=1 affects exec output. See CLI reference.

The installer writes platform-specific absolute runtime and image paths in /etc/bhatti/config.yaml. Illustrative Linux excerpt — keep the paths produced by your installer:

engine: krucible
data_dir: /var/lib/bhatti
api_socket: /var/lib/bhatti/api.sock
api_socket_gid: 123 # replace with the actual GID of the bhatti group
# No listen: by default; specifying it opts into plaintext TCP.
cgroups: auto
# default_egress: none
# mount_roots:
# - /srv/agent-workspaces
krucible_vmm: /var/lib/bhatti/runtime/bin/bhatti-vmm
krucible_netd: /var/lib/bhatti/runtime/bin/bhatti-netd
krucible_libdir: /var/lib/bhatti/runtime/lib
krucible_kernel_image: /var/lib/bhatti/runtime/kernel/<installed-lean-kernel>
krucible_base_image: /var/lib/bhatti/images/rootfs-minimal-amd64.ext4
SettingDefaultMeaning
enginekruciblelibkrun VMM on Linux KVM or Apple Silicon HVF.
data_dir~/.bhatti without server configSQLite, runtime, images, sandboxes and volumes. Installer sets an explicit server path.
api_socket<data_dir>/api.sockAlways-present local control API socket. Guest cannot reach it.
api_socket_gidunsetPositive group ID changes socket ownership to root:<gid> and mode to 0660; otherwise mode 0600. Installer sets this to the bhatti group’s GID. Bearer auth is still required.
listenunset / emptyOptional plaintext HTTP TCP control listener, in addition to the socket. Keep it on a trusted loopback/private interface; do not expose tokens to an untrusted network.
default_egressnonenone: no NIC; deny: NIC with explicit allow rules; public: public egress. Per-sandbox create policy can override this. Sibling access remains opt-in.
mount_rootsemptyExisting absolute host directories permitted as roots for live create --mount; empty disables mounts. Sources are canonicalized and checked again on start; roots can’t expose bhatti’s data or loaded config files.
rate_limitssee belowPer-user API request budgets.
cgroupsautoPer-helper placement and resource accounting: auto, systemd or none. See Cgroups.
krucible_vmm, krucible_netd, krucible_libdir, krucible_kernel_imageautodetectionInstalled VMM, conditional network gateway, library and lean guest kernel paths.
krucible_base_imagenoneDefault tier’s ext4 image; the sandbox has a qcow2 overlay over its immutable content-addressed base.
krucible_block_rootimplied by base imageBlock-root boot mode.
krucible_socket_dir/tmp/bhatti-krShort vsock/control socket path directory.
public_proxy_listenunsetOptional path-based plaintext proxy listener for development; prefer domain mode for public HTTPS.
api_url, auth_tokenunsetCLI endpoint and bearer key, normally saved in the user’s config.
domain, backupunsetHTTPS domain mode and optional S3-compatible volume backups (below).

bhatti-netd is started per owner only if sandboxes use networking. There is no supported shared-network backend switch. See Networking for policy and Host mounts for create flags.

cgroups places VM helpers and per-owner network gateways for resource accounting. It does not impose CPU, memory or I/O limits; placement’s CPU weights are relative scheduling weights, not quotas.

ValueBehaviour
autoDefault. On Linux, use systemd scopes if PID 1 is systemd, cgroup v2 is mounted, and the system bus permits bhatti to create its units. Otherwise run without placement (none), logging the reason and reporting it on /health.
systemdRequire systemd placement. The daemon refuses to start if the requirements above are unavailable; a failed new-helper placement fails its create/start rather than running it unaccounted.
noneDisable cgroup placement. Useful on Linux hosts or containers without systemd; helpers are not placed in bhatti’s slice hierarchy.

On macOS there are no cgroups: auto reports the effective mode process, while explicit none reports none. systemd is not supported there.

Check the effective mode in GET /health, which reports the requested setting, selected mode and any fallback reason. See Host resource placement for the slice/scope hierarchy and daemon-upgrade behaviour.

rate_limits:
create: {per_minute: 30, burst: 10} # POST /sandboxes: create and fork
exec: {per_minute: 600, burst: 30} # exec, file writes, exec/shell websockets
read: {per_minute: 1200, burst: 60} # everything else, including destroy and snapshot resume

Each bucket is per user: it holds up to burst requests and refills at per_minute. Omitted or zero fields keep the defaults shown; neither zero field disables its bucket. A nonzero burst below 1, a negative rate, or a non-finite value stops the daemon at startup. A refused request is logged as a 429 with its bucket (rate_limit_bucket) and answered with Retry-After; see Users & Auth.

domain:
api_host: api.yourdomain.com
proxy_zone: yourdomain.com
tls_cert: /etc/bhatti/wildcard.pem
tls_key: /etc/bhatti/wildcard-key.pem
# Or use acme_email: you@example.com for per-alias Let's Encrypt certificates.

Configure both cert paths or acme_email. Domain mode serves the authenticated API at api_host, published aliases at <alias>.<proxy_zone>, TLS on :443, redirect/ACME on :80, and the local Unix control socket; there is no implicit internal TCP port. It ignores listen and public_proxy_listen. See Custom domain for DNS, certificate and restart steps.

backup:
s3_endpoint: https://s3.eu-central-003.backblazeb2.com
s3_region: eu-central-003
s3_bucket: bhatti-backups
s3_access_key: ...
s3_secret_key: ...
schedule:
- volume: workspace
cron: '0 3 * * *'
retention: 7

backup enables S3-compatible volume backup and restore. Without it, those endpoints return 501. A schedule is optional; volume names the volume, cron is a five-field expression, retention is the number of backups to keep. See Volume backups.

<data_dir>/
├── state.db SQLite database (WAL mode; owner-only, it holds key hashes and sealed secrets)
├── age.key Secret-encryption key
├── api.sock Local control API
├── runtime/ Installed VMM, netd, libkrun, lohar and kernel
├── images/
│ ├── rootfs-<tier>-<arch>.ext4 Symlink to the current tier base
│ └── bases/ Immutable content-addressed bases
├── sandboxes/<id>/ Sandbox overlays and stopped-state data
├── snapshots/<owner>/<name>/ Named memory/disk or filesystem snapshots
├── volumes/<owner>/ Persistent ext4 volume images
└── bhatti.log launchd service log on macOS

The installer defaults to /var/lib/bhatti on both Linux and macOS and writes its chosen data_dir to /etc/bhatti/config.yaml. If you use a different data directory, follow that config rather than hardcoding the default. The installed service is systemd on Linux (/etc/systemd/system/bhatti.service, journalctl -u bhatti) and launchd on macOS (/Library/LaunchDaemons/sh.bhatti.plist, <data_dir>/bhatti.log). The server logs its loaded config path at startup. Self-hosting covers backups and service operation.