Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Dodaios Control API
A local, authenticated HTTP API that lets Dodaios (formerly Personal Jarvis) — and any local agent (Codex CLI, Claude Code, a test harness) — do everything the user can do in the desktop app: read and change settings, switch brain/STT/TTS providers, switch the reply language, rotate provider keys, read the providers snapshot. It is the real, deterministic alternative to Computer-Use for self-configuration.
Mounted at /api/control/* on the same FastAPI server the desktop UI uses.
Implemented as a thin authenticated facade (dodaios/ui/web/control_routes.py)
over the production-ready layers — AtomicConfigWriter (atomic backup +
validate + rollback + audit), dodaios.brain.app_control (live provider switch),
and the keyring secret store. It reimplements none of them.
The per-user API key
Every install generates its own key on first boot (prefix jctl_, 256-bit). It
is not baked into the package — this is an open-source project, so each user
gets a unique key.
- Storage (cross-platform): OS keyring first (Windows Credential Manager /
macOS Keychain / Linux Secret Service, service
personal-jarvis, slotjarvis_control_api_key). On a headless Linux VPS without a Secret Service daemon the keyring silently fails, so the key falls back to a0600file atdata/.control_api_key(or$JARVIS_DATA_DIR). Read order: keyring → file →JARVIS_CONTROL_API_KEYenv seed. - Runtime reads: a successful lookup is serialized and cached for the life of the Dodaios process, then invalidated by an in-process key replacement. Forked children drop the cache. This keeps per-request Bearer checks from repeatedly decrypting the same operating-system credential.
- macOS upgrade repair: if the item was created by an older direct-Python
launcher, the first approved read re-creates the same value under the
verified canonical
Personal Jarvis.appcode-signing requirement. A private, non-secret owner stamp prevents repeat migrations. An unsigned development process is never allowed to perform or claim that repair. - Never exported into
os.environduring normal operation (a spawned worker would inherit it and leak it via/proc/<pid>/environ). - Where the user finds it: desktop app → API Keys → Access &
Integrations → Control Key (masked by default, Show/Hide, one-click Copy,
Regenerate behind a confirm dialog, or replace it with a user-chosen key —
min 12 chars,
[A-Za-z0-9._~-]). The browser lock screen (AuthGate) points to this section. Headless:GET /api/control/api-keyfrom the loopback interface, or read the key file.
Auth
Authorization: Bearer <key> on every /api/control/* route, constant-time
compared. The key — not the localhost binding — is the security boundary
(cloud-first): desktop binds 127.0.0.1; a VPS may bind 0.0.0.0 only when a
key exists (assert_bind_safe, fail-closed). The existing same-origin UI routes
(/api/settings/*, /api/provider/*) are unchanged and stay key-free. The
key-reveal/rotate endpoints additionally accept a loopback request so the
Settings panel can bootstrap the key before the user has it.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/control/auth/probe |
200 iff the key is valid |
| GET | /api/control/allowlist |
machine-readable list of mutable settings |
| GET | /api/control/config?path=… |
read a value (403 for protected paths) |
| PUT | /api/control/config |
write {path,value,reason} — SAFE applies, ASK returns pending_id |
| POST | /api/control/config/confirm |
apply an ASK-tier pending_id |
| POST | /api/control/config/reject |
cancel a pending mutation |
| PUT | /api/control/language |
convenience: set reply_language (auto/de/en/es/pt) |
| GET | /api/control/providers |
provider + settings snapshot |
| PUT | /api/control/providers/{tier} |
switch brain/tts/stt/subagent |
| GET | /api/control/secrets |
list secret slots (masked) |
| PUT/DELETE | /api/control/secrets/{key} |
set / delete a provider key |
| GET | /api/control/api-key |
reveal the key (loopback or Bearer) |
| POST | /api/control/api-key/rotate |
regenerate randomly ({confirm:true}) |
| PUT | /api/control/api-key |
set a user-chosen key ({value, confirm:true}; 422 on weak/invalid values, response is masked-only) |
Two languages (interface vs reply)
Dodaios has two language settings, both now backend-backed and in the allowlist:
ui.language(en/de/es) — the INTERFACE the user sees: every label, button and message. Formerly frontend-only localStorage; now a config key so voice/the Control API can change it. SAFE. When it changes, aUiLanguageChangedevent (and theConfigReloadedfrom the writer) is forwarded over/ws, so the open React UI switches language live — no reload, every OS. The frontend hydrates it on mount and pushes UI clicks toGET/PUT /api/settings/ui-language.brain.reply_language(auto/de/en/es/pt) — what Dodaios SPEAKS/writes back;automirrors the user's input language. SAFE, hot-reloads into the next turn.
The PUT /api/control/language verb (and the voice command) set both when
given a concrete code, so "switch the language to German" changes the whole
experience; auto only affects replies.
SAFE vs ASK
brain.reply_language, brain.proactivity, tts.speed, ui.theme are
SAFE — they apply immediately. Language hot-reloads into the next turn (a
ConfigReloaded subscriber calls BrainManager.set_reply_language) with no
restart. brain.proactivity (off/balanced/high, how much initiative the
assistant takes) reloads the same way through
dodaios.brain.proactivity.apply_level; the assistant page sets it with
PUT /api/soul/initiative.
brain.primary, tts.provider, stt.* are ASK — PUT /config returns
needs_confirmation=true + a pending_id; confirm to apply. requires_restart
is reported honestly (e.g. STT re-init).
Status codes for config writes
| Status | When |
|---|---|
| 200 | Applied (SAFE), parked for confirmation (ASK, with pending_id), or confirmed and applied |
| 400 | Path is not in the allowlist, or pending_id is not a valid id |
| 403 | Protected path (secrets, safety lists) |
| 410 | pending_id expired (5 minutes) or was already confirmed or rejected |
| 422 | The value fails schema validation. An ASK-tier value is validated when it is proposed, so PUT /config refuses it before any pending_id exists |
| 500 | Backup, write, reload or rollback failed. The detail is a fixed sentence; the cause is in the Dodaios log |
POST /config/confirm answers 200 only when the change landed. A failed
apply is an error status, never 200 with ok: false. A confirmed or failed
entry is consumed either way, so propose the change again to retry.
POST /config/reject is idempotent and answers 200 for an unknown id.
Voice path
"Dodaios, switch your language to English" works end-to-end without this HTTP
API: the router brain already has the set_config_value tool (router tier), the
strict force-spawn guard does not intercept a plain language request, and
brain.reply_language is SAFE → applied → hot-reloaded. The Control API is the
agent path; the voice tool is the spoken path. Both go through the same
allowlist, the same atomic writer, and the same audit log.
The default skill
A built-in skill control-api (dodaios/skills/builtin/control-api/SKILL.md,
category: meta, shipped VALIDATED, no voice triggers) is copied into every
install's skills dir on first boot. It is the recipe a local coding agent reads
when asked "can you change something on my Dodaios?" — base URL, key location,
auth header, and curl examples for the allowlist/config/language/providers/
secrets endpoints. It has no voice triggers on purpose: a trigger matching
"switch language" would make the router run the skill body (which cannot make
HTTP calls) instead of calling the set_config_value tool.
Cross-platform / cloud-first
Pure FastAPI + stdlib secrets + keyring — all in the base install, so the
headless python:3.11-slim container boots it unchanged with no GUI extra. The
config path honours JARVIS_CONFIG (a writable file on a VPS where
PROJECT_ROOT may be read-only). Desktop-only settings (overlay/bar/ducking)
report requires_ui honestly rather than crashing on a server.
Known follow-up
Voice confirmation for ASK-tier mutations (the spoken "…confirm?" → "yes"
loop, SelfModFlowController) is not yet wired into the speech pipeline. SAFE
settings (the headline language switch) work on voice today, and ASK-tier
settings are fully usable via this Control API's confirm endpoint and via the
desktop UI — so this only affects spoken changes to ASK-tier settings.