# erlidev/eika architecture

> Architecture diagram of the GitHub repository erlidev/eika, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erlidev/eika
- Repository: https://github.com/erlidev/eika

## Overview

Eika is a Docker-native agentic coding harness. A user configures authentication, model providers, and a project through the web UI, then starts a session; the run manager drives an agent that builds model context and invokes tools. Workspace file access and commands go through sandbox containers, and the UI presents transcripts, terminal output, edits, and diffs. Major adjacent capabilities include search, MCP servers, profiles, and parallel subagents. Several backend links are supported by the source index; unsampled frontend and subsystem wiring is shown only where the README documents the capability.

Main entry points: [`internal/server/run_manager.go`](https://github.com/erlidev/eika/blob/main/internal/server/run_manager.go) (Run manager), [`internal/server/routes.go`](https://github.com/erlidev/eika/blob/main/internal/server/routes.go) (HTTP API), [`internal/tool/builtin/registry.go`](https://github.com/erlidev/eika/blob/main/internal/tool/builtin/registry.go) (Built-in tools), [`internal/workspace/host.go`](https://github.com/erlidev/eika/blob/main/internal/workspace/host.go) (Workspace lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Harness API"]
  node_eika["Harness process<br/>[main.go]"]
  node_api["HTTP API<br/>[routes.go]"]
  node_runmgr["Run manager<br/>[run_manager.go]"]
  node_store[("Persistent state<br/>[store.go]")]
  node_events["Event bus<br/>[bus.go]"]
end

subgraph group_agent["Agent Runtime"]
  node_agentcore["Agent context<br/>[context.go]"]
  node_sessions["Session history<br/>[store.go]"]
  node_tools["Built-in tools<br/>[registry.go]"]
  node_subagents["Parallel subagents<br/>[spawn.go]"]
end

subgraph group_workspace["Workspace Execution"]
  node_workspaces["Workspace lifecycle<br/>[host.go]"]
  node_executor["Sandbox executor<br/>[sandbox.go]"]
  node_daemon["Sandbox daemon<br/>[daemon.go]"]
  node_egress["Network egress<br/>[proxy.go]"]
end

subgraph group_integrations["Model Integrations"]
  node_search["Web search<br/>[engine.go]"]
  node_mcp["MCP servers<br/>[server.go]"]
  node_providers["Model providers<br/>[openai.go]"]
end

subgraph group_frontend["Web Interface"]
  node_web["Web application<br/>[App.tsx]"]
  node_webapi["API client<br/>[client.ts]"]
  node_sessionui["Session interface<br/>[SessionView.tsx]"]
  node_workspaceui["Workspace panels<br/>[queries.ts]"]
end

node_user(("User"))

node_user -->|"configures and starts"| node_web
node_web -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_api
node_eika -->|"starts server"| node_api
node_api -.->|"starts runs"| node_runmgr
node_runmgr -->|"drives agent"| node_agentcore
node_runmgr -->|"reads and records runs"| node_store
node_runmgr -->|"loads session"| node_sessions
node_runmgr -->|"selects provider"| node_providers
node_agentcore -.->|"offers tools"| node_tools
node_agentcore -->|"sends model context"| node_providers
node_tools -->|"executes in sandbox"| node_executor
node_runmgr -.->|"publishes run updates"| node_events
node_runmgr -.->|"supports child runs"| node_subagents
node_subagents -->|"records child results"| node_store
node_subagents -->|"emits child events"| node_events
node_tools -.->|"offers web search"| node_search
node_tools -.->|"offers MCP tools"| node_mcp
node_api -.->|"serves saved resources"| node_store
node_api -.->|"manages workspaces"| node_workspaces
node_workspaces -->|"provides workspace access"| node_executor
node_executor -->|"sends sandbox operations"| node_daemon
node_workspaces -.->|"restricts container network"| node_egress
node_user -->|"reviews run"| node_sessionui
node_sessionui -.->|"uses workspace panels"| node_workspaceui
node_workspaceui -->|"views files and diffs"| node_workspaces
node_api -->|"serves UI"| node_web

click node_eika "https://github.com/erlidev/eika/blob/main/cmd/eika/main.go"
click node_api "https://github.com/erlidev/eika/blob/main/internal/server/routes.go"
click node_runmgr "https://github.com/erlidev/eika/blob/main/internal/server/run_manager.go"
click node_store "https://github.com/erlidev/eika/blob/main/internal/store/store.go"
click node_events "https://github.com/erlidev/eika/blob/main/internal/event/bus.go"
click node_web "https://github.com/erlidev/eika/blob/main/web/src/app/App.tsx"
click node_webapi "https://github.com/erlidev/eika/blob/main/web/src/api/client.ts"
click node_sessionui "https://github.com/erlidev/eika/blob/main/web/src/features/session/SessionView.tsx"
click node_workspaceui "https://github.com/erlidev/eika/blob/main/web/src/features/workspaces/queries.ts"
click node_agentcore "https://github.com/erlidev/eika/blob/main/internal/agent/context.go"
click node_sessions "https://github.com/erlidev/eika/blob/main/internal/session/store.go"
click node_tools "https://github.com/erlidev/eika/blob/main/internal/tool/builtin/registry.go"
click node_subagents "https://github.com/erlidev/eika/blob/main/internal/subagent/spawn.go"
click node_search "https://github.com/erlidev/eika/blob/main/internal/search/engine.go"
click node_mcp "https://github.com/erlidev/eika/blob/main/internal/mcp/server.go"
click node_providers "https://github.com/erlidev/eika/blob/main/internal/provider/openai/openai.go"
click node_workspaces "https://github.com/erlidev/eika/blob/main/internal/workspace/host.go"
click node_executor "https://github.com/erlidev/eika/blob/main/internal/executor/sandbox/sandbox.go"
click node_daemon "https://github.com/erlidev/eika/blob/main/internal/eikad/daemon.go"
click node_egress "https://github.com/erlidev/eika/blob/main/internal/egress/proxy.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_eika,node_api,node_runmgr,node_store,node_events,node_user toneBlue
class node_agentcore,node_sessions,node_tools,node_subagents toneAmber
class node_workspaces,node_executor,node_daemon,node_egress toneMint
class node_search,node_mcp,node_providers toneRose
class node_web,node_webapi,node_sessionui,node_workspaceui toneIndigo
```

## Components

### Harness API

- [Harness process](https://github.com/erlidev/eika/blob/main/cmd/eika/main.go): `cmd/eika/main.go`
- [HTTP API](https://github.com/erlidev/eika/blob/main/internal/server/routes.go): `internal/server/routes.go`
- [Run manager](https://github.com/erlidev/eika/blob/main/internal/server/run_manager.go): `internal/server/run_manager.go`
- [Persistent state](https://github.com/erlidev/eika/blob/main/internal/store/store.go): `internal/store/store.go`
- [Event bus](https://github.com/erlidev/eika/blob/main/internal/event/bus.go): `internal/event/bus.go`

### Agent Runtime

- [Agent context](https://github.com/erlidev/eika/blob/main/internal/agent/context.go): `internal/agent/context.go`
- [Session history](https://github.com/erlidev/eika/blob/main/internal/session/store.go): `internal/session/store.go`
- [Built-in tools](https://github.com/erlidev/eika/blob/main/internal/tool/builtin/registry.go): `internal/tool/builtin/registry.go`
- [Parallel subagents](https://github.com/erlidev/eika/blob/main/internal/subagent/spawn.go): `internal/subagent/spawn.go`

### Workspace Execution

- [Workspace lifecycle](https://github.com/erlidev/eika/blob/main/internal/workspace/host.go): `internal/workspace/host.go`
- [Sandbox executor](https://github.com/erlidev/eika/blob/main/internal/executor/sandbox/sandbox.go): `internal/executor/sandbox/sandbox.go`
- [Sandbox daemon](https://github.com/erlidev/eika/blob/main/internal/eikad/daemon.go): `internal/eikad/daemon.go`
- [Network egress](https://github.com/erlidev/eika/blob/main/internal/egress/proxy.go): `internal/egress/proxy.go`

### Model Integrations

- [Web search](https://github.com/erlidev/eika/blob/main/internal/search/engine.go): `internal/search/engine.go`
- [MCP servers](https://github.com/erlidev/eika/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [Model providers](https://github.com/erlidev/eika/blob/main/internal/provider/openai/openai.go): `internal/provider/openai/openai.go`

### Web Interface

- [Web application](https://github.com/erlidev/eika/blob/main/web/src/app/App.tsx): `web/src/app/App.tsx`
- [API client](https://github.com/erlidev/eika/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Session interface](https://github.com/erlidev/eika/blob/main/web/src/features/session/SessionView.tsx): `web/src/features/session/SessionView.tsx`
- [Workspace panels](https://github.com/erlidev/eika/blob/main/web/src/features/workspaces/queries.ts): `web/src/features/workspaces/queries.ts`

### Other components

- **User**

## Connections

- User → Web application: configures and starts
- Web application → API client: requests data
- API client → HTTP API: calls API
- Harness process → HTTP API: starts server (evidence: `cmd/eika/main.go`)
- HTTP API → Run manager: starts runs
- Run manager → Agent context: drives agent (evidence: `internal/server/run_manager.go`)
- Run manager → Persistent state: reads and records runs (evidence: `internal/server/run_manager.go`)
- Run manager → Session history: loads session (evidence: `internal/server/run_manager.go`)
- Run manager → Model providers: selects provider (evidence: `internal/server/run_manager.go`)
- Agent context → Built-in tools: offers tools
- Agent context → Model providers: sends model context (evidence: `internal/agent/context.go`)
- Built-in tools → Sandbox executor: executes in sandbox
- Run manager → Event bus: publishes run updates
- Run manager → Parallel subagents: supports child runs
- Parallel subagents → Persistent state: records child results (evidence: `internal/subagent/spawn.go`)
- Parallel subagents → Event bus: emits child events (evidence: `internal/subagent/spawn.go`)
- Built-in tools → Web search: offers web search
- Built-in tools → MCP servers: offers MCP tools
- HTTP API → Persistent state: serves saved resources
- HTTP API → Workspace lifecycle: manages workspaces
- Workspace lifecycle → Sandbox executor: provides workspace access (evidence: `internal/workspace/host.go`)
- Sandbox executor → Sandbox daemon: sends sandbox operations (evidence: `internal/executor/sandbox/sandbox.go`)
- Workspace lifecycle → Network egress: restricts container network
- User → Session interface: reviews run
- Session interface → Workspace panels: uses workspace panels
- Workspace panels → Workspace lifecycle: views files and diffs
- HTTP API → Web application: serves UI
