Internal architecture
Inside a Kern host
The fixed Unix identities, services, sockets, database roles, and privilege boundaries inside one host.
One host, narrow services
Kern separates the operator UI, agent runtimes, internet policy, bundled tools, workspaces, embeddings, tunnel connector, and database into distinct Unix identities. A compromised component reaches only its own files, sockets, network destinations, and database tables.
OperatorSSH / HTTPS
One Kern host · fixed Unix identities
kern-adminAdmin API
kern-workspaceChat · Apps · Memory · Schedules
kern-agentAgent runtimes + agent-home
kern-proxyInternet policy
kern-toolsBundled actions + secrets
PostgresPeer-authenticated roles
Unix sockets + peer credentialsnftables + scoped DB rolesRoot-owned bounded helpers
Fixed UIDs and GID
Service ids are pinned so ownership on durable volumes remains meaningful when Kern replaces the disposable root volume and its /etc/passwd file.
| Identity | ID | Owns or runs |
|---|---|---|
| kern-admin | UID/GID 47741 | Admin API and full admin-state database role |
| kern-proxy | UID/GID 47742 | Policy proxy, proxy CA material, and Git quarantine |
| kern-agent | UID/GID 47743 | Codex, Claude Code, Grok, Hermes, schedules, and agent-home |
| cloudflared | UID/GID 47744 | Optional Cloudflare Tunnel connector |
| postgres | UID/GID 47745 | Local kern_admin Postgres cluster |
| kern-tools | UID/GID 47746 | Bundled tool service and credentials |
| kern-agent-network | UID/GID 47748 | Read-only policy and network-event service |
| kern-workspace-api | GID 47749 | Peer-authenticated admin socket shared group |
| kern-workspace | UID/GID 47750 | Chat, Apps, Memory, Schedules, and Workspace agent API |
| kern-embedding | UID/GID 47751 | Local socket-activated ONNX text encoder |
What each principal cannot do
| Principal | Important boundary |
|---|---|
| kern-operator | The deliberate exception: human SSH access has full passwordless sudo. |
| kern-admin | No internet egress; only a fixed set of root-owned helper commands may cross boundaries. |
| kern-agent | No sudo, database role, direct off-host network, secrets store, or access to other services' state. |
| kern-tools | No sudo; only tool tables, shared secret-key read, DNS, and outbound HTTPS for tool APIs. |
| kern-proxy | No sudo; narrow policy/event database grants and only DNS plus TCP 80/443 egress. |
| kern-workspace | No secrets or egress; DML only on its named Workspace tables. |
| kern-agent-network | Read-only policy/event database grants and no egress. |
| kern-embedding | No home directory, secrets, database, or network namespace. |
Deliberate boundary crossings
The identities above never speak over the network. Each pair that must cooperate gets exactly one Unix socket, and the kernel tells the listening service which user is on the other end, so a caller cannot claim to be someone else.
| Caller | Reaches | Over this socket | And may only |
|---|---|---|---|
| kern-agent | kern-tools | /run/kern-tools/tools.sock | Call bundled tools that the operator enabled. Credentials stay on the kern-tools side. |
| kern-admin | kern-tools | /run/kern-tools/tools.sock | Manage and test tool configuration. No other user is admitted on this socket. |
| kern-agent | kern-workspace | /run/kern-workspace/agent.sock | Use the bounded /agent/ routes for chat, memory, Apps, and schedules. |
| kern-agent | kern-agent-network | /run/kern-agent-network/agent-network.sock | Read its own policy and denials. Read-only, and kern-tools gets no policy access this way. |
| kern-workspace | kern-admin | /run/kern-admin-api/workspace.sock | Call allowlisted host thread routes, such as sending or stopping a turn, authorized by the fixed kern-workspace-api group. |
| kern-admin, kern-workspace | kern-embedding | /run/kern-embedding.sock | Ask for an embedding. The encoder reads only the root-owned local model. |