Configuration and running the service
Mob is one service that owns the SQLite database; the desktop app, browser, TUI and channels are its clients. Start from config.example.yaml.
Files and environment
Section titled “Files and environment”The configuration reference lists file keys,
CLI flags, MOB_ variables, defaults and precedence.
On macOS the default file is ~/Library/Application Support/mob/config.yaml;
on Linux normally ~/.config/mob/config.yaml. YAML and JSON are accepted.
Model providers and keys live in providers.json beside it (see
Model providers); plugin settings live in the database.
mob config check validates both files without printing credentials.
Live reload
Section titled “Live reload”- The service watches the configuration file’s directory, so atomic replacement
works. Each reload rejects unknown fields and validates a complete candidate
before applying it. Syntax errors, unsafe permissions, deletion and invalid
values keep the last valid configuration; diagnostics omit file contents and
appear in stderr, the background log and
/api/runtime. - Changing
addr,data_dir,state_dir,demo,driver,tokenoragents.confinementrequires a restart, as do environment changes and removing the watched directory. - Files must be regular (not symlinks), at most 64 KiB, and not group- or
world-writable on Unix.
providers.jsonmust be owner-only (chmod 600); on Windows protect it with the user directory’s ACLs. A missing default file is fine; a missing or malformed explicitly selected one fails startup. - Active turns keep the model they started with.
Who owns the service
Section titled “Who owns the service”mob startruns the service in the background;mob statusreports it and any reload errors;mob stopauthenticates to it and waits for shutdown. Start, status and stop must use the same address and data-directory overrides.- The desktop app and
mob tuiconnect to an existing service or start one in the background. Closing either client leaves the service, channels and schedules running; usemob stopto stop the background service.mob servestays tied to its terminal. No login item or system service is installed. mob tuiuses the normal connect-or-start lifecycle and hands the service URL and token to the terminal UI in memory, not as command arguments. The source entry (bun run tui:pilot) only attaches to an existing service.- The database owner holds a process lock; clients use HTTP rather than opening the SQLite file.
Access
Section titled “Access”- Authentication represents one local user, not a multi-user permission system.
The desktop app gets the token directly.
mob opensigns a browser in with a one-time link that expires after 5 minutes; otherwise openhttp://127.0.0.1:8787and paste the token fromMOB_DATA_DIR/token. The browser keeps it until Disconnect. mob token rotatereplaces the managed token, signs out every client and stops turns started with the old token. A token supplied through configuration is fixed until restart and cannot be rotated by Mob.- Files declaring
tokenmust be owner-only on Unix (chmod 600). Prefer a file or environment variable for secrets: CLI flags are visible in the invoking process’s arguments. Background startup forwards secret flags through its child environment instead of child arguments. - Browser dev origins
http://localhostandhttp://127.0.0.1on ports 5173 and 5174 and theweb_urlorigin are allowed; the desktop window loads the service itself.