Files and environment

Everything the worker writes, where it writes it, what mode it uses, and every SOBA_ variable that moves it.

`~/.soba/`#

Path	Mode
`worker.json`	`0600`	The pairing token and cached broker URL
`policy.json`	n/a	The owner's machine grant. Absent = a read-only default
`models.json`	n/a	OpenAI-compatible endpoints and their cost classes
`service.env`	`0600`	Environment for the installed service: API keys, `SOBA_*` overrides
`workspace/`	n/a	The default root a run may execute in, when no policy widens it
`audit.log`	n/a	Every approval decision, appended

Environment variables#

Variable
`SOBA_HOME`	Relocates every piece of worker state at once. Default `~/.soba`
`SOBA_POLICY_FILE`	Keep the machine grant somewhere else
`SOBA_SERVICE_ENV_FILE`	Keep the service environment file somewhere else
`SOBA_BROKER_URL`	Broker host; overrides the cache
`SOBA_PAIR_TOKEN`	Pairing token; overrides the cache
`SOBA_OLLAMA_URL`	A non-default Ollama base URL

SOBA_HOME is useful in containers, and it is what keeps the test suite out of a real $HOME.

Precedence#

a variable in the real environment
        ▸ beats ▸
~/.soba/service.env
        ▸ beats ▸
the cached values in ~/.soba/worker.json

Why keys live in a file and not the unit#

A systemd unit is world-readable by design.

So the pairing token stays in worker.json (0600), and everything else (an endpoint's apiKeyEnv key, a SOBA_* override) goes in service.env (0600), which the worker loads itself at startup. One mechanism on both platforms.

The exception is the handful of variables that decide where state lives (SOBA_HOME and friends): those cannot come from a file whose own path they determine, so they go in the service definition. They are locations, not secrets.

The service definition#

Platform
macOS	launchd, per-user by default
Linux	systemd, `--system` for a system unit

What gets recorded is a stable path to the installed binary. A path inside a package manager's cache is never recorded: caches get pruned, and a service pointing into one works today and breaks weeks later with no visible cause.

See Keeping it running.