FrontierAgent
Open-source terminal agent runtime: a stateful ReAct agent or a coordinator with parallel sub-agents, working in a sandboxed filesystem for long-horizon research and file-based deliverables.
Evidence shows path policy (read-only /inputs, read-write /workspace, controlled /outputs), fail-closed sandbox, approval gates on writes/deletes/installs, denial of some operations even with --yes, and journaled mutations enabling /revert. pyproject carries Dependabot-driven security floors for transitive deps (cryptography, urllib3, etc.) — above-average practice. Deductions: approval flow, sandbox isolation, and deny-even-with---yes implementations are not present in the submitted files; these are README assertions only. Keys are just recommended via .env with no redaction or leakage-prevention mechanism shown. source_attribution has full LICENSE, citations, and named code paths, but the publisher is unverified, capping it at 2.
README, pyproject, and CI are mutually consistent (entry points and apodex alias, extras split, test paths, ruff rules) — 3. Dependency availability deducted: runtime deps use floating >= floors rather than locks (CI uses uv sync --locked but the user quick start does not); the GPU stack itself admits driver/CUDA/SGLang mismatch fails late as opaque errors. Failure messaging has partial evidence (tests assert 'escapes workspace', 'symbolic links' messages; fail-closed claims), but the broader error surface is not shown — 2.
Deployment matrix covers macOS/Linux/WSL2/GPU containers, multi-arch Docker images, and Chinese docs; audience/scenario clarity earns 3. Environment fit has an install chooser, GPU compatibility matrix, and compose validation — 3. Capability boundaries include REACT_NO_WEB/SWARM_NO_WEB, --concurrency 1 guidance, and an authoritative benchmark registry, but these are mostly documented claims without code — 2. Trigger precision has narrow evidence (attachment contract differing between react/agent_team in tests) — 2.
Information architecture (doc index, layered directory map) and install notes (multi-platform, Chinese, Docker, GPU) are well evidenced — 3. Full Apache-2.0 text — 3. Deductions: no CHANGELOG and version stuck at 0.1.0 with a SECURITY support table listing only 0.1.x, so versioning_changelog is 1; naming stability relies on a retained apodex alias with legacy baggage — 2; examples concentrate in quick start and no FAQ — 2; known limitations (fragile GPU stack, private image packages cannot be pulled anonymously) are disclosed but scattered — 2; maintenance responsibility has security response SLAs and CI gates but no public release cadence or maintainer commitment — 2.
Output usability claims (/outputs host mapping, run dir with checkpoint/trace/trajectories, task-board sidebar) are not backed by submitted implementation code — 2. Marginal value: ReAct + Agent Team + eval suite share one engine with deliberate layering, which is differentiated, but performance gains rest entirely on vendor self-reported numbers — 2. Cost-benefit includes token-budget docs and concurrency-multiplication warnings, yet is entangled with GPU costs and a free-tier promotion without neutral assessment — 2.
Claims are traceable: performance tables cite an arXiv report; behavioral claims name concrete code paths (frontier_agent/infra/config.py etc.) — 2. Cross-source corroboration: CI (pytest under bwrap), the py.typed gate, and attachment tests (path escape, symlink rejection, session scoping) genuinely corroborate some README security claims — an above-average plus; however core trust claims (approvals, /revert, traces) have no code backing — 2. Fact/inference separation is weak: the README interleaves marketing (limited-time free API), self-assessed benchmark numbers, and mechanism description with no internal distinction — 1.
- This is a static review with no execution; core security mechanisms (approval gates, sandbox isolation, /revert) are README assertions only — audit the actual implementations in apodex/ and plugins/tools/ before use.
- Runtime dependencies use floating >= floors and the user quick start does not use --locked; pin and audit the dependency tree for production.
- Benchmark numbers come solely from the publisher's own reports and a linked arXiv paper — interested-party evidence, not independently reproduced; do not treat as sole selection basis.
- The README mixes a limited-time free-API promotion with mechanism documentation; separate marketing from technical fact.
- The project itself admits GPU/SGLang version mismatch fails as opaque CUDA/Triton errors; verify the compatibility matrix before GPU deployment.
- Publisher identity is unverified; vulnerability disclosure relies only on [email protected] with no third-party attestation.
What does this agent do, and when should you use it?
FrontierAgent from ApodexAI is an open-source agent runtime, terminal product (TUI), and evaluation suite for long-horizon research and file-based work. It ships two native workflows: Stateful ReAct, where a single stateful agent researches, reads and writes files, runs commands, and iterates in a task-scoped sandbox; and Agent Team, where a coordinator maintains a task board, delegates independent work to bounded parallel sub-agents, and synthesizes their reports. The codebase is deliberately layered — frontier_agent/ (loop, scheduling, registries, AgentBus), plugins/tools/, workflows/, apodex/ (terminal CLI/TUI), and benchmarks/ — so each layer can be reused independently. File access follows one sandbox policy: /inputs read-only, /workspace read-write, /outputs for persistent deliverables. Deployment spans macOS native or Docker, Linux native/bubblewrap/Docker, and local SGLang GPU serving, connecting to any OpenAI-compatible endpoint. The same workflow engine powers the benchmark runner bundled with fourteen public benchmarks.
After installation, launch the TUI with uv run frontier-agent --mode react|agent_team --cwd /path/to/project. In ReAct mode, a single stateful agent reads documents from /inputs, searches and analyzes in /workspace, invokes the web, shell, file, and sandbox tools (plugins/tools/), and writes deliverables to /outputs. In Agent Team mode, the coordinator decomposes the request into a task board (add_task/update_task events render live in the TUI sidebar), dispatches bounded parallel sub-agents, collects structured reports, and synthesizes the final result. Mutating operations show a diff and require approval unless --yes is set; sessions are checkpointed, every action is traced locally, /revert undoes session changes, and --resume continues a saved run. Typing while the agent runs queues the instruction for the next safe turn boundary. The evaluation layer runs each benchmark question in an isolated subprocess via benchmarks.public.runner.run_subprocess, supporting resumable multi-run experiments and deterministic or model-based judges. Model access is configured through OPENAI_API_KEY, OPENAI_BASE_URL, and OPENAI_MODEL; set SWARM_NO_WEB=1 or REACT_NO_WEB=1 to disable web tools.
- Researchers who need deep investigation across a codebase or document set: point --mode react --cwd /repo at the project, and the agent reads materials read-only, works in the sandbox, and writes a report to /outputs.
- Analysts facing broad questions that benefit from decomposition: use --mode agent_team to let a coordinator split the question, run parallel sub-agent investigations, and synthesize conclusions.
- Engineering teams benchmarking self-hosted model agents: the subprocess runner covers fourteen benchmarks including BrowseComp, Humanity's Last Exam, and file-grounded suites, with artifact collection and per-failure reruns.
- Local GPU users serving their own model: configure SGLang via scripts/run-linux-gpu.sh after checking nvidia-smi against the GPU compatibility matrix, then run native or Docker-based serving.
- Users avoiding a local Python environment: pull the published linux/amd64 or linux/arm64 image and run
docker compose run --rm agent.
What are this agent's strengths and limitations?
- Two production-grade workflows out of the box: Stateful ReAct for focused research, and Agent Team with a coordinator, bounded parallel sub-agents, and a live task board — a relatively rare natively-terminal multi-agent orchestration in open source.
- Complete safety model: unified /inputs (read-only) / /workspace / /outputs sandbox path policy, diff-plus-approval gates on mutations, fail-closed authorization, session checkpoints, local traces, /revert, and --resume.
- Evaluation built into the framework: the same workflow engine drives a subprocess benchmark runner with isolated runs, resumable multi-run experiments, concurrency control, and failure reruns across a registry of fourteen public benchmarks.
- Multiple documented deployment paths: macOS/Linux native, bubblewrap, Docker, multi-arch prebuilt images, and local SGLang GPU templates for RTX 4090/5090-class hosts — Docker is never mandatory.
- Requires an OpenAI-compatible endpoint; the README defaults to the Apodex-1.1 API platform (promoted with a two-week free offer), so compatibility with other providers' tool-calling behavior must be verified by the adopter.
- Local SGLang serving is pinned to reviewed NVIDIA driver / CUDA / SGLang tracks, and mismatches surface late as opaque CUDA or Triton kernel errors during model load — a real operational debugging cost.
- Scientific and document packages are intentionally optional in native mode and are installed on demand into <project>/.apodex/runtime/native, meaning first runs may incur extra setup latency and network dependencies.
- Benchmark evaluation requires manually downloading datasets and configuring judge credentials (some benchmarks need SERPER/JINA API keys), and the open-source GDPval harness deliberately excludes the agentic pairwise grader.
How do you install or deploy this agent?
Prerequisites: Git, Python 3.12, uv, and an OpenAI-compatible model endpoint (Docker optional).
- Clone and sync:
git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent
uv sync --python 3.12 --extra dev
cp .env.example .env- Add your endpoint to .env:
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name
SERPER_API_KEY= # optional web research tools
JINA_API_KEY= # optional web research tools- Or use the one-command scripts:
./scripts/run-macos.sh/./scripts/run-linux.sh(hosted endpoint), or./scripts/run-linux-gpu.sh --install-system-deps --setup-onlyfor a native SGLang environment on a Linux NVIDIA GPU. - Docker route: pre-built linux/amd64 and linux/arm64 images are published to GitHub Container Registry —
cp .env.example .env && docker compose run --rm agent, no local Python required. Chinese-language macOS/Linux install guides are included (docs/install/macos.zh-CN.md and others).
How do you use this agent?
Interactive TUI:
uv run frontier-agent --mode react --cwd /path/to/project
uv run frontier-agent --mode agent_team --cwd /path/to/projectLaunch with a task:
uv run frontier-agent --mode agent_team --cwd /repo "Research the alternatives, verify the evidence, and write a report"
uv run frontier-agent --mode react --cwd /repo -p "explain src/main.py"
uv run frontier-agent --mode agent_team --no-tui "compare these implementations"
uv run frontier-agent --resumeAttach read-only documents before the TUI starts (repeatable): --input ~/Downloads/claim.pdf --input ~/Desktop/photo.jpg. While a workflow runs, typing queues a follow-up at the next safe turn boundary; writes, deletions, and package installs require approval (or --yes), and /revert undoes file mutations. Evaluation smoke test: uv run python -m benchmarks.public.runner.run_subprocess --benchmark browsecomp --pipeline stateful-react-agent --profile default --limit 1 --concurrency 1 --out ./results/smoke (after downloading datasets per docs/eval.md and uv sync --extra eval --extra sandbox --extra document-readers).
FAQ
Do I have to use Apodex's own model?
Which of my files can the agent access?
Can I intervene mid-run and resume sessions?
Can I use it without a GPU or self-hosted model?
docker compose run --rm agent.