Configuration¶

Sistemo can be configured via a YAML config file, environment variables, or both.

Config file¶

Create ~/.sistemo/config.yml:

port: 9090
max_vcpus: 16
default_bandwidth_mbps: 100

The daemon loads this file on startup. Show the effective config with:

sistemo config

Priority¶

Environment variables > YAML file > defaults

If you set PORT=7070 as an env var and port: 9090 in the YAML file, the daemon listens on port 7070.

Available settings¶

YAML key	Env var	Default	Description
`port`	`PORT`	7777	Daemon HTTP port
`host_interface`	`HOST_INTERFACE`	`eth0` (auto-detected if absent)	Network interface for NAT
`min_disk_free_mb`	`MIN_DISK_FREE_MB`	512	Minimum free disk (MB) before deploy is blocked
—	`HOST_API_KEY`	(none)	API key for network-exposed deployments (env-var only, not in config.yml)
—	`SISTEMO_REGISTRY_URL`	`https://registry.sistemo.io/images/`	Override the default image registry URL (env-var only)
`max_vcpus`	`MAX_VCPUS`	64	Max vCPUs per machine
`max_memory_mb`	`MAX_MEMORY_MB`	262144 (256 GB)	Max memory per machine
`max_storage_mb`	`MAX_STORAGE_MB`	1048576 (1 TB)	Max storage per machine
`default_bandwidth_mbps`	`DEFAULT_BANDWIDTH_MBPS`	0 (unlimited)	Default download limit per machine
`default_upload_mbps`	`DEFAULT_UPLOAD_MBPS`	0 (unlimited)	Default upload limit per machine
`default_iops`	`DEFAULT_IOPS`	0 (unlimited)	Default disk IOPS limit
`default_disk_bw_mbps`	`DEFAULT_DISK_BW_MBPS`	0 (unlimited)	Default disk bandwidth limit
`bridge_subnet`	`BRIDGE_SUBNET`	10.200.0.0/16	Machine bridge subnet (CIDR)

Examples¶

Change daemon port¶

# ~/.sistemo/config.yml
port: 9090

# Or via env var
PORT=9090 sudo sistemo up

Limit machine resources¶

# ~/.sistemo/config.yml
max_vcpus: 8
max_memory_mb: 16384
default_bandwidth_mbps: 50
default_upload_mbps: 10

Change bridge subnet¶

The default machine subnet is 10.200.0.0/16. If this conflicts with your VPN, Kubernetes, or other network, change it:

# ~/.sistemo/config.yml
bridge_subnet: "10.50.0.0/16"

Note

Changing the subnet requires restarting the daemon and redeploying machines. Existing machines will lose connectivity since their IPs are on the old subnet.

Set API key¶

HOST_API_KEY is an environment variable only — it cannot be set in config.yml. Set it in the shell or in the systemd unit override:

# Shell
HOST_API_KEY=my-secret-key sudo sistemo up

# Systemd unit override
sudo systemctl edit sistemo
# Add: Environment=HOST_API_KEY=your-secret-key

Warning

CLI requests from localhost bypass authentication automatically. Set HOST_API_KEY if you expose the daemon to the network. The dashboard uses its own JWT-based login for browser sessions.

Override image registry¶

SISTEMO_REGISTRY_URL is also env-var only:

SISTEMO_REGISTRY_URL=https://my-registry.example.com/images/ sistemo machine deploy debian

Config validation¶

The daemon validates all config values on startup. Invalid values produce a clear error:

$ MAX_VCPUS=-1 sudo sistemo up
fatal: invalid config: MAX_VCPUS must be > 0 (got -1)

$ BRIDGE_SUBNET=bad sudo sistemo up
fatal: invalid config: BRIDGE_SUBNET "bad" is not valid CIDR

$ PORT=99999 sudo sistemo up
fatal: invalid config: PORT must be 1-65535 (got 99999)

Check	Rule
`PORT`	1–65535
`MAX_VCPUS`	> 0 (warns if > 4x host CPUs)
`MAX_MEMORY_MB`	> 0
`MAX_STORAGE_MB`	> 0
`MIN_DISK_FREE_MB`	>= 0
`BRIDGE_SUBNET`	Valid CIDR, at least /24
`HOST_INTERFACE`	Must exist on the system (if explicitly set)

Data directory¶

All state lives in ~/.sistemo/:

~/.sistemo/
├── sistemo.db          # SQLite database (machines, IPs, port rules)
├── config.yml          # Config file (optional)
├── bin/firecracker     # Firecracker binary
├── kernel/vmlinux      # Guest kernel
├── ssh/sistemo_key     # SSH key pair
├── vms/{id}/           # Per-machine directory (rootfs, config, logs)
├── images/             # Cached rootfs images
└── volumes/            # Persistent volumes

Override with --data-dir:

sudo sistemo up --data-dir=/opt/sistemo