The machine grant

There are two policies in Soba and they are not the same object:

1. The policy your app requests on a run.
2. The policy the machine's owner grants: this file.

The worker resolves them by intersection and the local grant always wins. See Security model.

The default, with no file at all#

{
  "roots": ["~/.soba/workspace"],
  "defaultCwd": "~/.soba/workspace",
  "allowTools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
  "askTools": [],
  "denyTools": [],
  "maxConcurrency": 2,
  "maxTimeoutMs": 600000,
  "permissionMode": "deny",
  "allowRuntimes": [],
  "allowAppTools": true,
  "allowMeteredKeys": false,
  "approver": "local",
  "grants": "ask"
}

Read-only tools inside ~/.soba/workspace. Not $HOME, not the launch directory. Nothing is askable, so the approval path is inert until the owner opts into it. A machine becomes more useful only when its owner says so, in a file they control.

A realistic grant#

{
  "roots": ["~/Projects"],
  "allowTools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch", "Edit"],
  "denyTools": ["Bash"],
  "maxConcurrency": 2,
  "askTools": ["Write"],
  "maxTimeoutMs": 600000,
  "permissionMode": "ask",
  "approver": "local",
  "allowAppTools": true,
  "allowMeteredKeys": false
}

Every field#

allowTools versus askTools#

allowTools runs with no questions asked. askTools is the approval ceiling: tools the model may attempt, each one gated by a live yes/no.

A yes can only ever select from that set. So even an approver that says yes to everything, including a compromised one, cannot widen the machine past what its owner pre-authorised. That property is what makes "approver": "remote" safe to offer at all.

allowMeteredKeys#

Default false, and the default is the interesting part.

The worker inherits the owner's shell, and that shell may hold ANTHROPIC_API_KEY. Passing it through means a run advertised as user-subscription quietly bills their API account while Soba, reading a free cost class, charges nothing. Both sides lose and neither is told.

So a runtime whose key is set is withheld unless the owner sets this flag — advertised to nobody, and reported to the owner naming the variable. Setting the flag serves those runtimes instead, re-classified as frontier, so the meter and the wallet agree again.

The key itself is never removed from the environment. Which of their own credentials a person's CLI may use is not ours to decide, and Anthropic's terms for running Claude Code inside another product say so in as many words.

grants#

Default "ask". This is the one field here that decides whether the machine may be asked to become more permissive — and the wording is the whole design:

a broker may ask to widen; only a person at the machine may say yes.

An app can send a folder request. The worker does not act on it: it puts the question to whoever is standing at that machine, and on a literal yes it runs exactly what soba-worker allow <dir> --write runs, into exactly this file.

A request comes in one of two shapes, and neither of them reads the disk:

Three things it cannot do, whatever a broker sends:

• approver: "remote" can never answer one. That channel asks the app, and an app approving its own request for more permission is the escalation this whole model exists to prevent. A machine set to remote refuses folder requests outright and says so.
• It cannot make writing automatic. A yes adds the root and makes Write, Edit and Bash askable there. Every one of them still stops for its own yes.
• It cannot ask about a folder that is not there. A directory that does not exist is refused before a dialog is drawn, so a request cannot be used to probe what is on the disk. Nothing anywhere lists a directory: an earlier version answered "what folders are in here" so a dashboard could draw them, and it was removed — enumerating somebody's folders to fill in a form is a read of their disk that nobody asked them about.

Every decision, yes or no, is appended to ~/.soba/audit.log.

Relocating the file#

SOBA_POLICY_FILE points the worker at a different grant; SOBA_HOME relocates every piece of worker state at once. Both are useful in containers. See Files and environment.