# egin
A filesystem-first framework for durable backend agents. An agent is a folder; one Rust binary runs, serves, evaluates and benchmarks it. Models come from the You.com Inference Router, the web from You.com Search and Contents, and tools run in a microVM per session (microsandbox).
*egin* is Basque for "to do, to make".
Scope and roadmap: [TAKE_SCOPE.md](TAKE_SCOPE.md).
## Quick start
```bash
export YDC_API_KEY=... # or put it in .env.local
cargo build --release
./target/release/egin init my-agent --template research # basic, research, ops or support
./target/release/egin run my-agent "Who maintains SQLite, and under what license?"
```
| Command | What it does |
|---|---|
| `egin init
[--template t]` | Write a starter agent folder |
| `egin info ` | Resolved config, tools, skills, subagents, schedules, MCP connections, channels |
| `egin models` | Router models with context limits and prices |
| `egin run ""` | Run one prompt. `--yes` approves tools, `--session ` resumes, `--set key=value` overrides config |
| `egin chat ` | Interactive session |
| `egin serve --port 8787` | HTTP API, event stream, channels and schedules |
| `egin eval ` | Run `evals/` under every variant; `--model`, `--variant`, `--split`, `--task`, `--jobs` |
| `egin bench --agent ` | Terminal-Bench 2 (or converted SWE-bench) tasks in microVMs, one arm per variant |
| `egin evolve --model m` | Edit a model's profile from eval traces, keeping only edits that score better |
| `egin report ...` | One HTML page from results folders |
## Agent folder
```
my-agent/
agent.toml model and switches
instructions.md system prompt
memory/*.md appended to the system prompt; the `memory` tool edits memory/notes.md
skills//SKILL.md listed in the prompt, loaded on demand with the `skill` tool
tools/.json + tools/.sh any executable: JSON arguments on stdin, result on stdout
middleware/pre_tool runs on the host with {"tool","args"} on stdin; a non-zero exit blocks the call
connections/.toml MCP servers: `command = [...]` (stdio) or `url = "..."` (HTTP), `safe = [...]`
channels/webhook.toml signed webhook; channels/slack.toml for the Slack Events API
subagents// a nested agent folder, called with the `task` tool
schedules/.toml `cron = "0 9 * * *"` or `every_secs`, plus `prompt`; run by `egin serve`
profiles/.toml per-model switch defaults; profiles/.md adds per-model instructions
evals/.toml prompt + check (shell, run in the sandbox) and/or expect (substring)
evals//task.toml the same, with evals//files/ copied into the workspace first
evals/variants.toml named sets of config overrides; `external = ""` runs another harness instead
workspace/ mounted at /workspace in the VM
.egin/ sessions (egin.db), file index, tool output
```
Precedence: built-in defaults < `profiles/.toml` < `agent.toml` < `--set`. `profile = false` ignores the profile.
## Switches (agent.toml)
| Key | Default | Meaning |
|---|---|---|
| `model` | `kimi-k3.1-pro` | Any id from `egin models` |
| `tool_style` | `typed` | `bash` leaves only the bash tool |
| `web` | `client` | `server` lets the router run search and page fetches; `off` |
| `search_mode`, `search_count`, `freshness`, `include_domains`, `exclude_domains` | `highlights`, 5 | You.com Search options; `exclude_domains` also blocks fetches and filters results the API lets through |
| `exclude_terms` | `[]` | Withhold search results and fetched pages containing any of these strings (case-sensitive), for evals whose answers are republished |
| `batching` | `true` | Several tool calls per turn; safe ones run concurrently |
| `planning` | `false` | Adds the `plan` tool |
| `compaction`, `tool_output_max` | `true`, 8000 | Truncate long tool output on entry; the full text is saved to `.egin/out/` in the sandbox |
| `elision`, `elide_at`, `keep_recent` | `true`, 0.5, 6 | Stub out old tool output once the context passes that share of the limit |
| `summarisation`, `summarise_at` | `true`, 0.75 | Summarise old turns past that share |
| `memory_max` | 0 (off) | Adds the `memory` tool, capped at this many bytes |
| `index` | `false` | Adds `search_files`: full-text and metadata search over the workspace (SQLite FTS5) |
| `approval` | `ask` | `never` runs bash and file writes without asking |
| `max_turns`, `max_cost` | 60, 0 (off) | Per-session limits |
| `sandbox` | `auto` | `auto`: microsandbox where the host supports it (KVM, Apple Silicon, WHP), else `local` with a warning. `daytona`: Daytona cloud sandboxes (`DAYTONA_API_KEY`). `docker` / `docker-cloud`: Docker Sandboxes, local microVM or Docker's cloud, through the signed-in `sbx` CLI. Cloud backends copy the workspace up once and don't sync it back; `secrets` need microsandbox |
| `image`, `cpus`, `memory_mb`, `idle_timeout`, `workdir` | `python:3.13-slim`, 2, 2048, 600 | The session VM |
| `network` | `["*"]` | VM egress: `["*"]` all, `[]` none, or domains (`".example.com"` for subdomains) |
| `secrets` | `[]` | `[{ name = "API_KEY", host = "api.example.com" }]`: the VM sees a placeholder; the real host env value is substituted only on requests to that host |
| `context_limit` | from `/v1/models` | Override the model's context window |
## Sandboxing
Each session gets its own microVM (`egin-`), created on the first tool call. The agent's workspace is bind-mounted at `/workspace` and its `tools/` folder read-only at `/egin/tools`. The VM stops after `idle_timeout` seconds and restarts on the next call. After a crash it is reconnected, or replaced if its creation was cut off. It is removed when the session is deleted or an eval run ends. With `sandbox = "local"`, commands run on the host as a process group that is killed whole on timeout. microsandbox is pinned (`=0.7.15`); after bumping it, run `cargo test --test sandbox`.
## HTTP API
| Route | Body | Result |
|---|---|---|
| `POST /sessions` | `{"message"?}` | `{"id"}`; starts a run when a message is given |
| `POST /sessions/{id}/messages` | `{"message"}` | Continue a session |
| `GET /sessions/{id}` | | Status, stats, messages |
| `DELETE /sessions/{id}` | | Stop it, remove its VM, delete its records |
| `GET /sessions/{id}/events?after=` | | SSE: stored log replayed, then live events (`token`, `assistant`, `tool_call`, `tool_result`, `approval_request`, `done`, ...) |
| `POST /sessions/{id}/approvals` | `{"call_id", "allow"}` | Answer an `approval_request`; the answer is stored and survives a restart |
| `POST /sessions/{id}/cancel` | | Stop a running session |
| `POST /channels/webhook` | `{"text", "thread"?}` | HMAC-SHA256 signed (`X-Egin-Signature: sha256=`); one session per thread |
| `POST /channels/slack` | Slack Events API | Signature and replay checked; replies in the thread |
## Durability
Sessions live in `/.egin/egin.db` (SQLite). The loop is driven only by the stored messages, so a killed run resumes from the last stored message and completed model calls are never repeated. `egin serve` resumes interrupted sessions on start. A side-effecting tool call that was running when the process died is not re-run blindly: the model is told its effects are unknown and checks the state first. Several processes may share one agent folder: a writer waits up to 60 s for the database lock.
## Observability
`EGIN_LOG=json` writes every stored event to stderr as one JSON line. With `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) set, sessions, model calls and tool calls are exported as OTLP/HTTP spans, one trace per session.
## Benchmarks
```bash
git clone https://github.com/laude-institute/terminal-bench-2 ../tb2
egin bench ../tb2 --agent bench/tb2 --subset bench/tb2/subset.txt --model deepseek-v4.1-flash
egin report bench/tb2/results/ --title "Terminal-Bench 2 subset" -o results.html
```
The Terminal-Bench images are amd64-only, so `egin bench` rebuilds each task as an arm64 microVM from its Dockerfile, forks it per arm, and grades with the task's own `tests/test.sh`. Numbers compare arms on identical environments; they are not comparable to the official leaderboard. `--oracle` runs the reference solutions to validate the rebuilt environments. `bench/swebench/prepare.py` converts SWE-bench Verified instances into the same task format (arm64 setup scripts from swebench 3, graded by swebench's log parsers), sealed so the upstream fix is unreachable: base-commit history only, GitHub/PyPI/djangoproject blocked, grader offline. `bench/eve-arm` runs eve's default harness as an arm on the same VMs, metered by a proxy in front of the router that also serves egin's web tools, so both harnesses search alike. Epoch AI rates both Terminal-Bench and SWE-bench Verified as flawed (scoring defects; SWE-bench is also contaminated), so treat their numbers as arm-vs-arm comparisons only.
Two suites Epoch rates as verified run through `egin eval`:
```bash
python3 bench/simpleqa/prepare.py out/simpleqa --n 100
egin eval out/simpleqa --model deepseek-v4.1-flash --jobs 8
uv run --with pandas --with pyarrow python bench/graphwalks/prepare.py out/graphwalks --mode file
egin eval out/graphwalks --model deepseek-v4.1-flash --jobs 4
```
- **SimpleQA Verified**: short factual questions, graded by a judge model pinned in each task (`judge = { answer, model }`; only CORRECT passes). The arms are web via egin's client tools, web via the router, and closed-book (no web, no VM network).
- **GraphWalks** (128K and shorter): BFS and parent queries, graded by exact match of the `Final Answer: [...]` set (`answer_set`). `--mode inline` is the canonical prompt and mostly measures the model. `--mode file` moves the graph into `graph.txt`, so the agent reaches it through tools; it measures the harness and is not comparable to published scores.
## Code layout
| Path | What lives there |
|---|---|
| `src/main.rs`, `src/cli.rs` | Entry point and the `egin` subcommands |
| `src/app.rs`, `src/telemetry.rs` | Shared state, the event bus, OTLP spans |
| `src/agent.rs` | Loading the agent folder, config precedence, profiles |
| `src/run.rs`, `src/model.rs`, `src/tools.rs` | The loop, the router client, built-in tools |
| `src/store.rs`, `src/index.rs` | SQLite sessions and events, the FTS file index |
| `src/server.rs`, `src/channels.rs`, `src/mcp.rs` | HTTP/SSE API, webhook and Slack, MCP clients |
| `src/sandbox/` | `microvm`, `daytona`, `docker` backends behind one `exec` |
| `src/eval/` | Eval runner, `bench` (Terminal-Bench, SWE-bench, external harnesses), `evolve`, `report` |
## Tests
```bash
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```
`tests/common/` holds a scripted mock of the router, search and contents APIs that speaks the real SSE wire format, so the production client is what runs. The suites are split by area: `agent_loop.rs`, `tools.rs`, `channels.rs` (HTTP API, webhook, Slack), `eval.rs` and `rate_limit.rs`. `tests/sandbox.rs` boots real microVMs (skipped without virtualization) and runs the Daytona and Docker Sandboxes backends when their credentials are present.
Environment: `YDC_API_KEY`, `EGIN_BASE_URL` (default `https://api.you.com/v1`; any OpenAI-compatible endpoint works), `EGIN_SEARCH_URL` (default `https://ydc-index.io/v1`), `EGIN_LOG`.