What an agent is
An agent in Okesu is a markdown file with YAML frontmatter. The frontmatter declares identity, the LLM provider, the tools the agent can call, and the JSONL events it’s expected to emit. The body of the file is the system prompt the LLM sees on every run.
That’s it. No SDK, no runtime framework. The daimon parses the spec, drives the LLM in a turn-by-turn loop with the declared tools available, and watches for the JSONL events the agent emits. When a finding event lands, it goes to the control plane.
The agent definition is portable across every dispatch shape: a daimon running it locally, a federated CP running it on a child, a job-mode pull from an offline node — same spec, same behaviour.
The JSONL contract
An agent emits a stream of newline-delimited JSON events. The two that matter to the control plane are:
finding— a security signal: severity, title, optional category (process/file/network/cert/cloud), evidence, dedup key, attributes.orchestration_result— a single structured payload at the end of a run, surfaced as{{stepN.result}}in downstream orchestration steps. Optional but powerful for chained playbooks.
Other event types (logs, progress, tool calls) are ignored by the CP but visible in the run’s transcript. Agents are also free to emit nothing at all — a “no findings on this host” run is meaningful information.
Authoring an agent
A minimal agent looks like this:
---
name: edr-investigator
version: “1”
description: triage suspected C2 callbacks
provider: claude
model: claude-mythos-preview
effort: medium
maxTurns: 30
timeout: 5m
tools:
- bash
- read_file
- search
---
You investigate suspected command-and-control callbacks on this host.
Use ps, netstat, lsof, /proc to gather evidence. When you find a high-confidence
indicator, emit a finding event with the appropriate severity.
The same agent definition works whether the daimon is local-only or behind a federated CP — the dispatch mode is decided at the orchestration step, not the agent.
Tools an agent can call
An agent’s tools: list declares which capabilities the LLM can invoke during a run. Each tool is a typed function the daimon’s runtime exposes — bash for shell access, read_file for filesystem inspection, search for pattern matching across content, write_file for emitting artefacts, web_fetch for HTTP requests.
Adding a new tool is two changes: a small Go function on the daimon side that implements the call, and a one-line addition to the agent’s frontmatter. Tools are scoped to the agent that declared them; an agent without bash in its list can’t shell out, regardless of what the prompt asks for.
Built-in agents
Okesu ships with a small library of agents covering common security operations:
edr— Linux EDR running on a 5-minute schedule.instance-integrity— file-integrity monitoring on critical paths.instance-threat— IMDS abuse, container escapes, cryptomining detection.sre-health— TLS expiry, deployment frequency, recent incident patterns.edr-investigator— interactive triage agent invoked by orchestrations.forensic-collector— volatile-state snapshotting for incident response.
The full catalog is in the platform’s Agents tab; each spec is a complete worked example you can copy and adapt.
In the platform
The Agents tab in the Control Plane is the agent catalog. Markdown-frontmatter specs are sourced from ~/.claude/agents and the project’s own agents/ directory; provider badges show whether each agent is wired to Claude or Codex.
The agent catalog — markdown specs surfaced as a browseable library.
Where to next
- Daimons — what executes the agent.
- Orchestrations — sequence agents into playbooks.
- Install Okesu — bootstrap a CP and your first daimon.