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.
Agent routines
Routines run on the task store and scheduler (dodaios/tasks). Each routine
belongs to an agent, appears in its Routines rail, and executes
through that agent's canonical chat with its current instructions and permissions.
Creating a routine never grants additional plugin permissions.
Model seat
A routine is pinned to a model seat at creation: by default the seat its owner runs on at that moment (provider, model, effort, subscription account). The run stays on that seat — it is never silently rerouted onto another provider chain (such as an API-key chain) when the seat has trouble. A failed seat fails the run honestly with a readable error instead of billing a different credential.
The seat is part of the routine and can be changed afterwards: the routine editor has a Model section (provider, model, effort, account) with a "follow the agent" choice that clears the pin so the routine tracks the owner's live seat again. Title, prompt or schedule edits keep the pinned seat untouched.
Unattended runs and API keys
Background work follows one billing rule (dodaios/brain/background_policy.py):
once a subscription is connected (a subscription login seen within the last
30 days), work nobody started by hand never bills a per-token API key. For
routines this means:
- Scheduled, triggered and webhook runs on a seat that answers through an
API key are skipped while a subscription is connected. The run starts no
model turn and opens no routine chat. The routine's execution history shows
the run as Skipped with the reason in plain words (the
skippedstep carries a reasoncode, e.g.api_key_seat, and the seat'sprovider), the owner's chat gets one "skipped" line saying why, and a recurring routine fires again at its next occurrence (a one-shot routine ends as failed with that reason). The routine is not moved to another seat: pick a subscription or local model for it to keep it running unattended. - A skipped webhook delivery is settled as
skipped, not replayed. The cause is a setting, not a passing outage: a timed retry would fail the same way every time, and replaying it once the setting changes would run an old event late. The next delivery runs normally once the seat may be used. - Run now is the person's own start: it runs on the routine's seat as chosen, key included.
- Subscription and local seats run as before.
- An install that never connected a subscription keeps billing the seat it picked, so a single-key setup still runs its routines.
Routines an agent set up on its own (autonomous follow-ups) are stricter: they wait for a subscription or local seat whenever their seat would bill a key.
The same rule covers an agent's unattended memory work (the post-turn review
and skill learning, dodaios/society/seat_brain.py): with a subscription
connected, an agent whose chat bills a key does not review on that key. The
review stays pending under its bounded retries and the agent's profile
(Learned working instructions) says why: last_review carries a
reason_code (api_key_seat, no_seat or seat_failed), the seat's
provider and the server's reason sentence. After the bounded retries the
review is dropped and last_review.state becomes dropped with its
attempts and the same reason, so the profile shows that it was given up and
why; the agent's next finished conversation gets a new review. An explicit
"remember that" request is still saved without a model call.
The assistant's own learning loop is the one exception: it runs on the
default provider's subscription when that is signed in and otherwise still
on the key (docs/dodaios-learning.md).
Configuring routines by chat
Examples of supported requests:
- "Every day at 8 in the morning, summarize new email."
- "Every weekday at 09:30 Los Angeles time, prepare my briefing."
- "On the first of each month, summarize last month's results."
- "Every January 15 at noon, prepare the annual checklist."
- "Every 30 minutes, check for changes and report new findings."
- "In two hours, remind me to review the report."
- "When a mission succeeds, summarize its result in this chat."
- "Move the morning briefing to 9, pause it, resume it, or delete it."
The agent inspects existing routine IDs before editing and reads back the saved schedule. Explicit requests use the existing direct-user authorization check; suggestions require approval. Scheduled turns cannot authorize their own configuration changes by quoting a previous user message.
Time and recurrence
The browser sends its IANA timezone with each chat message. Calendar routines
persist that zone together with a local HH:MM time. An explicitly requested
location overrides the browser zone. Without either, the agent asks; the server
timezone is not a substitute. Traveling does not silently move existing routines:
ask the agent to change their saved zone.
Calendar filters support Monday-based weekdays, days of the month, months, and an optional starting date. Combined filters must all match. Invalid month dates are skipped. A nonexistent spring-forward clock time is skipped, and a repeated autumn clock time fires only on its first occurrence. Normal daily 08:00 runs therefore remain at 08:00 across DST transitions.
Elapsed intervals retain their existing semantics. Older interval schedules are not guessed into calendar schedules; ask to update them. The frontend's daily composer and new template requests now include calendar timezone information. Legacy template API requests without a timezone retain interval semantics.
Dodaios must be running for triggers to execute. The scheduler's existing misfire policy skips stale recurring slots after sleep or downtime rather than replaying a backlog. The rail shows the saved zone and the next run in the viewer's zone.
Events
society_routines exposes loaded event names and fields. Routine creation rejects
unknown events, unknown filter fields, and unsupported filter operations. Filters
support equality, inequality, and and/or/not. max_firings: null means a
standing rule; finite limits are persisted through the event-delivery log.
A schema's presence does not guarantee a live publisher. External inbox, file, or application events require an integration that actually publishes them. If unavailable, the agent explains the gap and offers interval polling.
Webhooks and integration event hooks
Ask an agent, for example: "Create a webhook routine that summarizes a new
customer, but only when customer.vip is true." The saved trigger is
{"kind":"webhook","conditions":{"customer.vip":true}}. A named integration
event uses {"kind":"event_hook","event_name":"crm.customer.created"}.
Both kinds accept optional conditions, max_firings and cooldown_seconds.
Conditions compare scalar JSON fields; dotted paths access nested objects.
Use Connect webhook on the agent's routine. The app shows the endpoint and a masked, copyable credential. Credentials are stored through the existing portable secret store and never included in the routine specification or returned by the agent's routine tools. Rotation revokes the old credential without changing other routines.
Send a JSON object to POST /api/tasks/hooks/{task_id} using
Authorization: Bearer <token copied in the app>. GitHub-compatible senders can
instead use the same token as their webhook Secret: the receiver checks
X-Hub-Signature-256 against the exact raw body, following
GitHub's signature format.
External services need a reachable HTTPS address with the corresponding host
configured in Dodaios. Creating a routine does not open a tunnel or expose the
desktop automatically.
Authenticated integrations can publish named events to POST /api/tasks/events
with {"event_name":"crm.customer.created","payload":{"customer":{"vip":true}}}.
This endpoint needs the normal Control API credential or authenticated UI; a
single routine's webhook token cannot publish events or access other APIs.
It returns admission results for matching routines and cannot impersonate an
internal system event. Python integrations may publish RoutineEventReceived
on the existing EventBus after the task scheduler has bound its subscriptions.
Delivery behavior
- A
queuedresponse means the payload was persisted, not that the task finished. Execution goes through the owning agent's current policy and canonical chat. - Reuse
Idempotency-Keyfor Bearer-authenticated retries. Signed requests use the signed body hash so changing an unsigned delivery header cannot replay it. The latest 4,096 delivery receipts per routine are retained for deduplication; pending deliveries are never pruned. - Payloads are limited to 32 KiB, admission to 60 deliveries per minute per routine, and outstanding work to 100 deliveries. Cooldowns and finite lifetime budgets are checked before admission. Filtered payloads consume no budget.
- Pending work survives restart and waits while a routine is paused. New requests to paused or exhausted routines are refused. Deleting the task revokes its URL.
- Interrupted running work is recorded but never automatically replayed because an external side effect may already have happened. Inspect its result before manually retrying. Execution errors remain visible in the normal task history.
- External payloads are appended as untrusted data, not as new user instructions. Hooks grant no additional tool permissions and cannot authorize self-configuration.
tests/contract/test_routine_hooks.py covers scoped credentials, signatures,
tampering, replay, boolean filter roundtrips, durable queues, pause/resume,
limits and OpenAPI payload schemas. A live single-key Gemini check created a
webhook through chat, delivered an HTTP payload to fresh isolated SQLite stores,
executed the owner's chat, and suppressed a repeated delivery. Native macOS/Linux
execution and a completely fresh OS installation are not claimed.
Verification
The portable calendar contracts exercise UTC persistence, DST gaps and folds, fractional offsets, weekday/month/leap-day schedules, SQLite migration, pause/resume/hydration, finite event limits, and HTTP timezone isolation. Frontend tests cover schedule construction, both list projections and submission. A live Gemini run with one credential and fresh isolated SQLite stores verified chat creation and execution through the owning agent's canonical chat. This was not a clean operating-system installation. Browser checks cover light/dark rendering and creating a routine with the browser's timezone.