Worker CLI
Every verb, flag, environment variable and exit path of soba-worker, the command-line worker for machines with nobody sitting at them.
Most people never see this
A person connecting their own laptop uses Soba App, which carries
the worker inside it. This page is for a machine with no screen (a VPS, an always-on
box) where a command line is all there is.
Download the signed binary and put it on PATH. It has no dependencies and
needs no toolchain.
These are the worker, not the app: soba.so/app is the Soba
App, which is what a laptop wants.
Terminal
soba-worker login --broker https://soba.so/c/pk_soba_<connect key>
soba-worker # reuses the cached token + broker
soba-worker --pair <token> --broker wss://… # a token you already have
Verbs#
A verb only counts in first position, otherwise --label install would silently
become a command instead of a label.
| Verb |
|
login |
Pair in a browser, then start. No token to copy |
install |
Run in the background, and after reboot |
uninstall |
Stop and remove the service |
service-status |
Is it installed, and is it up? |
forget --app <id> |
Stop serving one app. Every other pairing stays |
With no verb, the worker simply runs.
Options#
| Flag |
|
--pair, --token <t> |
Pairing token, minted by the app you're connecting to |
--broker, --url, --cloud <u> |
Broker host (wss:// or https://). Cached after first use |
--runtime <id> |
Force a runtime (claude-code, codex). Default: first detected |
--label <l> |
Tag this machine so an app can route to it. Repeatable |
--status |
Show what this machine would offer, then exit |
--reset |
Forget the cached token and broker, then exit |
--version, -v |
Print the version |
--help, -h |
Show help |
With login#
| Flag |
|
--install |
Also install the service once paired |
--no-browser |
Print the URL instead of opening it |
--auto-install |
Install as soon as a run succeeds, without asking |
--no-install-prompt |
Never offer to install |
With forget#
A machine holds one pairing per app, so being done with one of them is not the same
as being done with the machine — --reset is that, and it takes every pairing with it.
| Flag |
|
--app <id> |
Which app's pairing to drop. Its id, not its name |
--erase |
Also remove it from this machine's history in ~/.soba/apps.json |
The token is deleted here and nothing is asked of the broker: it was the only copy, so
an app whose pairing is gone can no longer reach this machine. The audit log is never
touched — what ran here is the owner's record, and ending a pairing is not a reason to
destroy it.
It edits files and nothing else. A worker already running still holds the connection it
opened at startup, so restart it afterwards (the Soba app does this for you).
With install / uninstall#
| Flag |
|
--system |
A system unit rather than a per-user one (Linux) |
--status#
Reports, without contacting anything:
- each detected runtime, its version and its models
- its cost class and whether it is signed in
authHint for anything unusable: the owner's next step- whether the background service is installed, and whether it is up
Environment#
These override the cache:
| Variable |
|
SOBA_BROKER_URL |
Broker host |
SOBA_PAIR_TOKEN |
Pairing token |
Location variables are on Files and environment.
A real environment variable beats the saved one
So debugging a daemon does not mean remembering that ~/.soba/service.env exists.
Prerequisite#
An agent CLI installed and signed in: claude and/or codex. Runs execute on
that subscription; Soba never sees the credentials.
A signed-out CLI is withheld rather than advertised and failed at spawn.
Security posture, restated by --help#
Runs are confined to the roots in ~/.soba/policy.json. With no such file, this
machine grants read-only tools inside ~/.soba/workspace and nothing else. The
app can only narrow that, never widen it.