FrontierAgent: Apodex's Terminal Agent Runtime for Long-Horizon File Work

The problem FrontierAgent targets: long file-based tasks, not chat

Most agent frameworks are libraries. You get a loop, a tool registry, and the job of wiring a UI, a sandbox, and a way to inspect what happened. FrontierAgent ships those parts together: a terminal product, a workflow engine, and an evaluation suite, each in its own top-level directory so they can be reused separately. The README describes the project as an "open-source agent runtime, terminal product, and evaluation suite for long-horizon research and file-based work." That phrase sets the audience. It is for people whose agent needs to read inputs, write deliverables to a workspace, run shell commands, and leave a trail you can audit afterwards. If your use case is a single question and a single answer, the machinery here is heavier than you need.

ReAct and Agent Team: two workflows over one engine

The TUI exposes two modes. ReAct is one stateful agent that researches, reads files, writes deliverables, runs commands, and iterates inside a task-scoped sandbox. Agent Team adds a coordinator that maintains a task board, delegates independent work to parallel sub-agents, collects structured reports, and synthesizes the result. The task board is not a metaphor: add_task and update_task events render live in the TUI sidebar with pending, active, completed, blocked, and cancelled states. The README also mentions an optional fast reporter used for final evidence review.

Intervention works differently in each mode. Typing while an agent runs queues an instruction that is injected at the next safe turn boundary without discarding the active run. In Agent Team mode that instruction steers the coordinator, and sub-agents already running are allowed to finish. That is a deliberate choice: it keeps parallel work from being torn down mid-flight, at the cost of a delay before your correction takes effect.

How the sandbox and run directory fit together

Shell and file tools share one task-scoped filesystem with three mounts. /inputs is read-only, /workspace holds working state, and /outputs holds persistent deliverables. The README states that authorization and sandbox failures are fail-closed, which matters when a tool call is ambiguous.

On macOS with Docker, /outputs maps to .apodex/runs/<session-id>/outputs on the host, and the same run directory carries the checkpoint, trace, engine log, and trajectories. That layout is the part worth evaluating before you commit. Every action is traced locally, mutating operations show a diff and require approval unless --yes is set, /revert restores session changes, and --resume continues a saved run. The README does not document what happens to a run directory when two sessions target the same project concurrently, so treat that as unverified.

The repository splits responsibilities on purpose: frontier_agent/ holds the generic loop, scheduling, registries, AgentBus, and observers; plugins/tools/ holds web, shell, file, sandbox, and team tools; workflows/ holds the ReAct and Agent Team pipelines; apodex/ holds the CLI, approvals, sessions, traces, and Docker path; benchmarks/ holds the public harness plus FrontierSearchBench and FrontierChallenge.

Installing FrontierAgent and running a first task

The README lists Git, Python 3.12, uv, and an OpenAI-compatible model endpoint as requirements, with Docker optional. Clone the repository and sync the environment. The --extra dev flag is what the quick start uses; uv sync installs the lightweight terminal runtime, and scientific or document packages are installed later into <project>/.apodex/runtime/native when a task needs them.

git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent

uv sync --python 3.12 --extra dev
cp .env.example .env

Then fill in the endpoint. The .env.example file marks these three as required, and the remaining keys in it are optional.

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name

Start the single-agent workflow against a project directory. The --cwd flag points the sandbox at the files the agent may touch.

uv run frontier-agent --mode react --cwd /path/to/project

For the coordinator plus parallel sub-agents, switch the mode. You should see the task board in the sidebar as the coordinator adds and updates tasks.

uv run frontier-agent --mode agent_team --cwd /path/to/project

Optional web research tools are configured with SERPER_API_KEY and JINA_API_KEY in the same file. The README does not give a walkthrough of the first approval prompt, so expect to learn the diff-and-approve flow by encountering it.

Where FrontierAgent gets in the way

The version in pyproject.toml is 0.1.0. There are no retrieved releases, so you are tracking the main branch rather than a tagged artifact, and the README does not describe a deprecation policy or a compatibility guarantee for the workflow and plugin interfaces. Pin a commit if you build on top of plugins/tools/.

Approval prompts are a real cost. Every mutating operation shows a diff and waits unless --yes is enabled, which is the right default for a first run and an obstacle for batch work. Turning it off removes the check that the fail-closed design depends on.

Native mode installs task dependencies into <project>/.apodex/runtime/native, so a project directory accumulates a runtime tree alongside your files. The Dockerfile also documents that the harness venv is kept read-only and that model-run commands get a separate overlay venv, because a writable harness venv would let a model-installed package be imported by the harness on a later turn. That reasoning is sound, but it means native and container runs do not have identical isolation.

Finally, the README's benchmark image and the Apodex-1.1 API promotion are marketing surfaces. The evaluation harness is genuinely included, but the README does not publish the raw results behind the chart, so do not read the figure as an independent measurement.

FrontierAgent compared with a general agent library

A library such as a bare ReAct loop gives you the agent and nothing else. You supply the terminal UI, the approval flow, the sandbox, the trace format, and the benchmark runner. FrontierAgent bundles all of those and pays for it with opinions: a fixed three-mount sandbox layout, a checkpoint format you did not choose, and a task board that only exists in Agent Team mode. The trade is legibility for flexibility. If you need the agent embedded in an existing service with your own permission model, the bundled TUI and approval layer are overhead you will end up bypassing. If you need to hand an engineer a terminal command that produces auditable files, the bundle is the point.

Editorial conclusion

FrontierAgent suits engineers who want to run agent workflows locally, read every trace, and inspect deliverables as ordinary files. It is the wrong tool if you expect a hosted service, a stable 1.0 API, or a one-click installer for non-technical users: the version is 0.1.0 and the README's quick start assumes Python 3.12, uv, and an OpenAI-compatible endpoint you already have. Before adopting, verify that your endpoint works with the OPENAI_BASE_URL and OPENAI_MODEL keys, then start the TUI with uv run frontier-agent --mode react --cwd on a throwaway project so the first approval prompts and the .apodex/runs layout are visible before any real work runs.

Frequently asked questions

Official sources

1. ApodexAI/FrontierAgent on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README