Use this page as the map for the repository documentation. Pick the section that matches what you are trying to do; files listed as reference are most useful when changing that subsystem rather than when getting started.
| Goal | Read this |
|---|---|
| Understand the project and run a first task | Project README |
| Run the TUI with an existing LLM endpoint | English quickstart / 中文教程 |
| Learn the TUI panes, previews, approvals, and live steering | English user guide / 中文使用教程 |
| Install on any environment | Installation and deployment |
| Run FrontierAgent from a container | Docker and Compose |
| Run or configure a local NVIDIA/SGLang model | GPU and SGLang |
| Understand ReAct versus Agent Team | Workflow implementations |
| Run benchmark evaluation | Evaluation guide |
| Extend the framework | Developer guides |
Start with the installation chooser. It routes by operating model—hosted endpoint, Docker GPU host, custom cloud image, or an existing GPU container—instead of asking you to guess from the operating system alone.
| Environment | Canonical guide |
|---|---|
| macOS or Linux, fastest hosted-endpoint TUI setup | English quickstart / 中文教程 |
| macOS, hosted or remote endpoint | macOS / 中文详细版 |
| Linux, hosted or remote endpoint | Linux |
| Windows | WSL2 section in the Linux guide |
| Any host with Docker, no local Python | Docker and Compose |
| Linux NVIDIA host with Docker | Docker SGLang |
| Existing Linux GPU environment without nested Docker | Native SGLang |
| GPU cloud or custom OCI image | GPU platforms |
Read these in order when bringing up a local model:
- GPU compatibility explains supported runtime tracks and what must be recorded when certifying hardware.
- Choose the matching deployment guide from the table above.
- SGLang configuration reference documents every
.env.sglangsetting, safe tuning order, and upstream references.
The files under config/sglang/*.env.example are runnable templates; their
comments and the SGLang reference are the source of truth for those variables.
| Topic | Document |
|---|---|
| TUI panes, keyboard workflow, previews, approvals, and Agent Team intervention | English user guide / 中文使用教程 |
| CLI, TUI, themes, slash commands, approvals, and terminal internals | apodex/README.md (reference) |
| High-level architecture and sandbox boundaries | Framework architecture |
| Security policy and vulnerability reporting | Security policy |
The root README's job is the product overview, a short quick start, and results. Detailed operational behavior belongs in the focused documents above, so new instructions go there rather than into a second copy.
| Workflow | Use it for | Configuration reference |
|---|---|---|
| Stateful ReAct | One stateful agent doing sequential research and file work | Workflow README |
| Agent Team | Coordinator plus parallel sub-agents and optional reporter | Workflow README |
Those READMEs own profile selection and workflow-specific configuration. To create a new workflow plugin, use Writing a workflow instead.
- Evaluation guide: installation, judge configuration, dataset downloads, execution, filesystem contract, results, and progress.
- FrontierSearchBench evaluation: the one benchmark with an external cross-query scorer — isolation requirement, collect / export / score workflow, and scorer options.
- Benchmark registry: supported dataset keys, default pipelines, scoring implementations, repository layout, and how to add a benchmark.
docs/eval.md is the operator guide for everything the benchmarks share;
docs/eval-frontier-search.md carries only what is specific to
FrontierSearchBench. benchmarks/README.md is the registry and extension
reference; keeping those roles separate avoids duplicating setup instructions.
| Task | Document |
|---|---|
| Understand runtime flow, observers, teams, and package boundaries | Framework architecture |
| Author and register a workflow plugin | Writing a workflow |
| Develop and submit changes | Contributing |
| Understand the frozen Textual + Rich decision | TUI framework decision (design record, Chinese) |
| Compare context-offloading changes with an A/B run | Tool-result truncation A/B |
| Pick up the deferred context-offloading work | Context offloading follow-ups |
| Inspect release-facing changes | Changelog |
Subsystem READMEs live beside their code when they are primarily useful to
maintainers: apodex/,
benchmarks/,
deploy/huggingface/, and
tools/golden/. Publishing the public demo Space
has a condensed Chinese walkthrough in
README.zh-CN.md,
with that directory's English README.md as the authoritative version;
README.space.md beside them is the Space's own landing page, not repository
documentation.
When updating documentation, change the canonical page instead of copying a second set of commands:
- root
README.md: product story, capabilities, short quick start, and results; docs/install/: environment-specific installation and deployment;docs/install/docker.md: Compose, image pinning,docker run, and cloud deployment of the CPU agent container;.env.example: the runtime agent, web-tool, and document-reader variables, documented by its own comments;config/sglang/README.md: SGLang variables and tuning;- workflow READMEs: workflow behavior and profiles;
docs/eval.md: running and interpreting evaluations, including datasets and the eval-only credentials that are not in.env.example;docs/eval-frontier-search.md: FrontierSearchBench's external scorer, isolation requirement, and three-step workflow;benchmarks/README.md: benchmark registry and extension points;apodex/README.md: CLI/TUI subsystem reference;docs/framework.mdanddocs/workflows.md: framework development.
Prefer linking to a canonical section over repeating it. A small command that gets a reader started is fine; a second complete setup or troubleshooting guide usually is not.