agent-runner
One Rust binary agent without any user source code
A minimal, non-interactive AI agent runner in your server or container. Give it a folder with AGENTS.md and skills, it uses tools, MCP and skills and iterates until the task is done.
Multi-Provider LLM
Anthropic and OpenAI-compatible APIs. Swap models with one env var.
Planning Phase
Generates a step-by-step execution plan before acting. Preview with --plan-only.
Autonomous Loop
LLM call, tool use, repeat. Runs until task_done or max iterations.
Summarization
Automatically compacts long conversations to stay within context limits.
Filesystem Tools
ls, read, write, edit, glob, grep. Everything an agent needs to work with code.
Permission System
Allow/deny rules for read/write on specific paths. Sandboxed by default.
MCP Servers
Connect external tools via the Model Context Protocol (JSON-RPC).
Skills
Load custom instructions, references, and executable scripts per agent.
Timeouts & Limits
Per-tool timeout and overall run limit. Full TAT tracking in run.json.
Pipeline
Load Agent Folder
Reads AGENTS.md, agent-runner.json, .env, and skills.
Generate Plan
Optionally generates a step-by-step execution plan.
Agent Loop
LLM call → tool execution → repeat. Summarizes if context gets long.
Write Output
run.json, report, transcript, and trace log written to output directory.
Agent Loop
├── AGENTS.md # system prompt
├── agent-runner.json # config
└── skills/
└── search/
├── SKILL.md # instructions
├── references/ # docs
└── scripts/ # executables
What goes where
- AGENTS.md — The system prompt. Defines who the agent is and how it behaves.
- agent-runner.json — MCP servers, timeouts, permissions. LLM settings from env vars.
- skills/*/SKILL.md — Skill instructions injected into the system prompt at load time.
- skills/*/references/ — Reference documents the agent can use.
- skills/*/scripts/ — Executable scripts exposed as agent tools.
.env.{
"mcp_servers": {},
"timeouts": {
"tool_timeout_secs": 120,
"run_limit_secs": 3600
},
"agent": {
"max_iterations": 50,
"plan_required": true,
"execute_enabled": false
},
"permissions": [
{ "operations": ["read"], "paths": ["./*"], "mode": "allow" }
]
}| Variable | Required | Description |
|---|---|---|
LLM_PROVIDER | yes | anthropic or openai |
LLM_MODEL | yes | Model name (e.g. claude-sonnet-4-20250514) |
LLM_BASE_URL | no | Override base URL for OpenAI-compatible APIs |
LLM_API_KEY | yes | API key (or use provider-specific name) |
ANTHROPIC_API_KEY | if provider=anthropic | Anthropic API key |
OPENAI_API_KEY | if provider=openai | OpenAI API key |
{
"mcp_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
"env": {}
}
}
}cd agent-runner
cargo build --release
cp .env.example .env
./target/release/agent-runner --agent-dir ./my-agent --prompt "Fix the failing tests"| Option | Default | Description |
|---|---|---|
--agent-dir | required | Path to agent folder |
--prompt | required | Task prompt or path to a text file |
--plan-only | false | Generate plan and exit |
--max-iterations | 50 | Max agent loop iterations |
--output-dir | ./agent-output | Output directory |
--working-dir | . | Working directory for tools |
--tool-timeout | 120 | Timeout per tool call (seconds) |
--run-limit | 3600 | Maximum total run time (seconds) |
--verbose | false | Print iteration details |
--sandbox | false | Enable shell execution |
| Exit Code | Meaning |
|---|---|
0 | Task completed |
1 | Task failed |
2 | Max iterations or run limit exceeded |
3 | Configuration error |
ls list directory read_file read with pagination write_file write content edit_file find & replace glob find files by pattern grep search with regex execute run shell commands task_done signal completion write_todos track task list compact shrink context Benchmarks are approximate and based on community reports. Actual performance varies by task and model.