# FrontierAgent

> Terminal agent runtime with a stateful ReAct loop, a coordinator-plus-sub-agents team mode, and a bundled benchmark runner

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: Python
- Licence: Apache-2.0
- Repository: https://github.com/ApodexAI/FrontierAgent
- Website: https://www.apodex.com/
- Canonical page: https://ai-tldr.dev/tools/frontier-agent/

## In short

FrontierAgent is an open-source agent runtime, terminal product and evaluation suite from Apodex AI, aimed at long-horizon research and file-based work. The frontier-agent TUI ships two native workflows. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in Python and licensed Apache-2.0.

## Overview

FrontierAgent is an open-source agent runtime, terminal product and evaluation suite from Apodex AI, aimed at long-horizon research and file-based work. The frontier-agent TUI ships two native workflows. ReAct runs one stateful agent that researches, reads files, writes deliverables, runs commands and iterates inside a task-scoped sandbox. Agent Team puts a coordinator in front: it maintains a task board, delegates independent work to parallel sub-agents, collects their structured reports and synthesises the result.

File work is sandboxed by construction. Shell and file tools share one task-scoped filesystem where /inputs is read-only, /workspace holds working state and /outputs holds persistent deliverables; authorization and sandbox failures are fail-closed. Mutating operations show a diff and require approval unless --yes is set, sessions are checkpointed, every action is traced locally, /revert restores session changes and --resume continues a saved run. On macOS and Docker, /outputs maps to .apodex/runs/<session-id>/outputs on the host alongside the run's checkpoint, trace and trajectories.

The repository keeps its layers deliberately separate — a generic loop and scheduler, plugin tools, workflow pipelines, the terminal app, and a benchmark harness — so each can be reused on its own. The same workflow engine powers the benchmark runner Apodex uses to evaluate its models, and it drives any OpenAI-compatible endpoint, so it is not tied to Apodex's own API.

## What it does

- Two native workflows: a stateful ReAct single agent and an Agent Team coordinator with parallel sub-agents
- Live task board in the TUI sidebar with pending, active, completed, blocked and cancelled states
- Task-scoped sandbox with read-only /inputs, working /workspace and persistent /outputs, fail-closed on authorization errors
- Asynchronous intervention — type while a run is in flight and the instruction is injected at the next safe turn boundary
- Approval diffs, local traces, session checkpoints, /revert and --resume for recovery
- Bundled evaluation runner with deterministic artifact collection, concurrency and single-failure reruns

## Getting started

You need Git, Python 3.12, uv and an OpenAI-compatible model endpoint. Docker is optional. uv sync installs the lightweight terminal runtime; heavier scientific and document packages are installed on demand into the project's own runtime directory.

1. Clone and sync the environment

   Clone the repository and let uv create the Python 3.12 environment with the dev extra, then copy the example environment file.

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

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

2. Point it at a model endpoint

   Add any OpenAI-compatible endpoint to .env. The web research tools are optional and take their own keys.

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

# Optional web research tools
SERPER_API_KEY=
JINA_API_KEY=
```

3. Start the TUI in either mode

   Run the single stateful agent, or the coordinator with parallel sub-agents. --cwd scopes the run to a project directory.

```bash
# Stateful single-agent workflow
uv run frontier-agent --mode react --cwd /path/to/project

# Coordinator plus parallel sub-agents
uv run frontier-agent --mode agent_team --cwd /path/to/project
```

4. Find your deliverables and traces

   Outputs, checkpoints, traces, engine logs and trajectories all land under the session's run directory. Use /revert to undo session changes and --resume to continue a saved run. The docs index at docs/README.md covers installation, SGLang, workflow, evaluation and developer guides.

## When to use it

- Long-horizon research tasks where one agent must read sources, write files and iterate over many turns
- Fanning a large request out to parallel sub-agents and having a coordinator verify and synthesise their reports
- Running file-grounded work under an approval gate, with a diff before every mutating operation and a local trace afterwards
- Benchmarking agent workflows with a deterministic harness that collects artifacts and can rerun individual failures
