The daemon and the local API

oaken_core.daemon is the composition root. Core.open() builds the object graph once: the event bus, the plugin host and its store (migrations run here), queues, labels, jobs, the agent registry, the scheduler, the router, intake, the operation registry and the two servers. Core.start() then brings up units, in this order:

1. events, the event log, so plugin start-up is in the record;
2. trace;
3. console, before the host, so a plugin that fails to start cannot take it down;
4. host, the plugins (their jobs, schedules and MCP exposure are attached here);
5. scheduler;
6. jobs, the runner;
7. mcp, both MCP doors;
8. api, last, so nothing is asked of a half-started core.

Stopping runs the other way. The API ends its event streams and stops accepting, the MCP doors stop, jobs get 30 seconds (JOB_GRACE) to finish or hand their leases back, then the scheduler, the plugins and the store, the console, the trace and the event log. If a unit fails to start, the ones already up are stopped in reverse and the original error is raised. A failing stop is logged and does not block the rest. A process that is killed instead is covered by lease expiry, as for any worker (see jobs).

flowchart LR
  E[events] --> T[trace] --> C[console] --> H[host] --> S[scheduler] --> J[jobs] --> M[mcp] --> A[api]

python -m oaken_core.daemon   # the foreground process: Ctrl-C or SIGTERM stops it cleanly

The same lifecycle is available to Python in oaken_core.daemon.lifecycle: serve, detach, status, stop_gracefully and reload. The CLI's oaken start, restart, stop and reload are thin wrappers over them, and they work with no core running. status reads only the runtime file, so it needs no token and never starts anything.

oaken start and oaken restart run core in the background by default, in a new session with standard input and output on the null device. --fg keeps it attached to the terminal, logging to it.

oaken stop sends SIGTERM and waits --grace seconds (40 by default: the 30-second job drain and a margin). If core is still running then, it is killed and its runtime file is removed so the next start is clean. A killed core loses nothing: its jobs are retried when their leases expire. --no-kill reports an error instead. oaken restart takes the same two flags.

Reload

SIGHUP, oaken reload and the core_reload operation all ask the running process to rebuild itself on config.toml. The file is validated before anything stops, so a typo changes nothing. A rebuild keeps the same pid, runtime file and (when the port is 0) the same ports. If the new core cannot start, the old settings are put back. An unchanged file is a no-op.

Who it is: identity.daemon

A product built on core calls oaken_core.identity.configure(app=..., title=..., prog=..., daemon=...) once at start. daemon is the command that runs that product's core in the foreground. start spawns it as a child, so it must be a program that calls configure itself. The default is plain python -m oaken_core.daemon. app also names the home folder and its variable (OAKEN_HOME for core, OAKEN_GROVE_HOME for an app called oaken-grove), so one product never lands in another's folder.

Core logs structured lines to stderr, console or json by [log] format. A detached core has no stderr, so set [log] file to keep its logs: lines are written to that file as JSON as well as stderr. A relative path sits under the data directory. The file is created owner-only (0600) and rotates by size: at [log] file_max_bytes it rolls to .1, and [log] file_backups copies are kept. A sink that cannot be written never costs the process its log: the write is dropped. With no file, a table in the core database keeps the lines for [log] keep_days. [log] level and [log] levels (per logger) apply to every sink, and a reload picks up a change at once. Secrets are redacted and long values cut at 200 characters before a line is rendered. [log] events_file (default events.jsonl) records every bus event, one JSON line each.

While core runs, runtime.json in the runtime directory holds pid, host, port, console_port, version and started_at. It is created owner-only (0600) and it is the single-instance lock: it is created exclusively, with port 0 meaning "starting", before anything is opened. If it exists and its process is alive, the second start stops with "core is already running". If that process is gone the file is stale and is replaced. A clean shutdown removes it, and only the process that wrote it removes it. The port is filled in once both servers are listening, by writing a sibling file and renaming it, so a reader never sees half a file.

The API port defaults to 0: the kernel picks one and the runtime file says which. Pin it with [api] port. A reload keeps the port that was in use. If a pinned port is taken, core refuses to start and says why. The CLI finds core only through the runtime file (or --url and --token-file for a server started by hand), so with no file the answer is "core is not running" (exit 3).

On first start core makes a random 256-bit token and stores it as api_token in the config directory, mode 0600. A token file others can read is tightened to 0600 and used. Every request but one needs Authorization: Bearer <token>. Both sides are hashed, then compared in constant time. GET /v1/health is open and answers {"status": "ok"}, nothing more.

The person's MCP door has its own token (mcp_token, same rules). Agents have tokens of their own (oaken_agent_..., made by agent_create) that open only /v1/agent/ and /mcp/agent. See the swarm. A token is checked only against the surface its path is on, so a token for one is worthless on another.

A browser can send a request to 127.0.0.1:PORT from any page the user has open, so being on loopback is not protection. One guard wraps every route and checks, in this order:

The event stream is long-lived, so it holds no concurrency slot. Responses carry X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Cross-Origin-Resource-Policy: same-origin, X-Frame-Options: DENY and, on /v1/, Cache-Control: no-store. The server's access log is off, because a URL can hold a search. Errors are one JSON body, {"code", "message"}. Anything unplanned is internal (500) and is logged by type only, because its text could quote private data.

The registry has a caller class, which decides whether a person's confirm is accepted (see operations). Over HTTP:

• a request is cli unless it says otherwise;
• X-Oaken-Client: ui is a browser UI, the same privileges;
• X-Oaken-Client: mcp makes the request an agent's: it cannot confirm by saying so, only with the token from its own proposal, and operations closed to MCP are hidden and refused;
• anything else, including internal, is a 400. A header can lower privilege and never raise it.

The MCP server mounts at /mcp on the API listener as its own surface, with its own token and limits ([api] mcp_max_body_bytes, mcp_max_concurrent), and the mount, not a header, sets its class (ADR 0004). It is on unless [api] mcp_enabled = false (or the mcp_power operation turns it off); then it answers 503. A second door at /mcp/agent takes agent tokens and offers the job tools plus what the agent was granted. With the swarm off, no agent token is accepted. A door is exactly its own path.

Operations are not routed by hand. GET /v1/operations lists the registry, with JSON Schemas, as the caller may see it. POST /v1/operations/{name} calls one through the same client the CLI uses. The OpenAPI document is served at /v1/openapi.json. Everything else is small:

• GET /v1/events: server-sent events. Each has an id, a type (the event's class name) and a JSON body of ids and numbers, never private text. Send Last-Event-ID to resume from the in-memory ring ([api] event_ring_size, 1000). An id older than the ring, or from before core restarted, gets a gap event, which means "fetch again". A quiet stream sends a : heartbeat comment every [api] heartbeat_seconds (15).
• GET /v1/trace/stream: the trace as it happens, filtered by plugin, job_id, subject or kind. The trace holds private text, so this route needs the token like any other.
• /v1/agent/jobs/claim and /v1/agent/jobs/{id}/heartbeat, complete and fail: the swarm's protocol.

The console is a second listener, always on 127.0.0.1. It has no host setting, and the settings model refuses extra keys, so nothing in config.toml can widen the bind. Its port is [console] port (62536 by default, 0 for any free one). It has no login. Its guard asks only that the request really is from this machine and from the console's own pages:

• the TCP peer must be loopback (403 otherwise);
• Host must be 127.0.0.1 or localhost with the console's port (or a *.localhost name a plugin adds, which a browser resolves to this machine and cannot be rebound);
• a form post needs a same-origin Origin (or null, which browsers send on a same-site form) and no Sec-Fetch-Site: cross-site, or it is 403;
• a post must be a form (application/x-www-form-urlencoded, 415 otherwise) under 256 KB;
• every response carries a Content-Security-Policy with no script at all, so a console page cannot run one.

The console is core's own: no plugin can switch it off, and it starts before the plugins so a broken plugin cannot take it down.

Not covered: a process running as the same user can read the token file and do what the user can. The change log records what it did.

• The ring is in memory: a restart is a gap for every client.
• Per-agent rate limits beyond the lease and hourly quotas in the swarm.