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.
Loading and CLI credentials
Section titled “Loading and CLI credentials”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.comauth_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.
Server settings
Section titled “Server settings”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: krucibledata_dir: /var/lib/bhattiapi_socket: /var/lib/bhatti/api.sockapi_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-workspaceskrucible_vmm: /var/lib/bhatti/runtime/bin/bhatti-vmmkrucible_netd: /var/lib/bhatti/runtime/bin/bhatti-netdkrucible_libdir: /var/lib/bhatti/runtime/libkrucible_kernel_image: /var/lib/bhatti/runtime/kernel/<installed-lean-kernel>krucible_base_image: /var/lib/bhatti/images/rootfs-minimal-amd64.ext4| Setting | Default | Meaning |
|---|---|---|
engine | krucible | libkrun VMM on Linux KVM or Apple Silicon HVF. |
data_dir | ~/.bhatti without server config | SQLite, runtime, images, sandboxes and volumes. Installer sets an explicit server path. |
api_socket | <data_dir>/api.sock | Always-present local control API socket. Guest cannot reach it. |
api_socket_gid | unset | Positive 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. |
listen | unset / empty | Optional 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_egress | none | none: no NIC; deny: NIC with explicit allow rules; public: public egress. Per-sandbox create policy can override this. Sibling access remains opt-in. |
mount_roots | empty | Existing 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_limits | see below | Per-user API request budgets. |
cgroups | auto | Per-helper placement and resource accounting: auto, systemd or none. See Cgroups. |
krucible_vmm, krucible_netd, krucible_libdir, krucible_kernel_image | autodetection | Installed VMM, conditional network gateway, library and lean guest kernel paths. |
krucible_base_image | none | Default tier’s ext4 image; the sandbox has a qcow2 overlay over its immutable content-addressed base. |
krucible_block_root | implied by base image | Block-root boot mode. |
krucible_socket_dir | /tmp/bhatti-kr | Short vsock/control socket path directory. |
public_proxy_listen | unset | Optional path-based plaintext proxy listener for development; prefer domain mode for public HTTPS. |
api_url, auth_token | unset | CLI endpoint and bearer key, normally saved in the user’s config. |
domain, backup | unset | HTTPS 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
Section titled “Cgroups”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.
| Value | Behaviour |
|---|---|
auto | Default. 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. |
systemd | Require 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. |
none | Disable 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
Section titled “Rate limits”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 resumeEach 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 mode
Section titled “Domain mode”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
Section titled “Backup”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: 7backup 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 directory layout
Section titled “Data directory layout”<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 macOSThe 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.