Installation
ProtoAgent currently runs from source. The Rust CLI embeds the Python core with PyO3, so both the Rust toolchain and the Python environment must be available.
Prerequisites
| Tool | Why it is needed |
|---|---|
| POSIX host (macOS/Linux) | Required by native recoverable Coder filesystem tools. |
| Python 3.12 or newer | Runs core/protoagent_core and ProtoLink. |
| Rust and Cargo 1.85 or newer | Builds cli/, including PyO3 0.29.3. |
| A model provider | Ollama, LM Studio, llama.cpp, OpenAI-compatible local server, or a cloud API provider. |
| Node.js 20 or newer | Runs the Docusaurus documentation site. |
Clone And Create Python Environment
git clone https://github.com/nMaroulis/protoagent.git
cd protoagent
python3 -m venv .venv
source .venv/bin/activate
pip install -e core
The core install includes ProtoLink's HTTP, LLM and MCP extras and compatible
SDK constraints. Use this install when upgrading too; ProtoLink 0.8.1's
Anthropic adapter needs anthropic<1.
The core imports are resolved from core/ by the Rust CLI at runtime. The CLI
also checks common .venv/lib/python3.x/site-packages paths so ProtoLink and
provider extras can be found when the binary starts from either the repo root or
the cli/ folder. The editable core install exposes the protoagent-core
package metadata and keeps protoagent_core.__version__ available to tools.
ProtoLink 0.8.1 is required for native action correction, automatic capability selection and no-change rejection, alongside owned local subagents, context policies/hooks, evaluation, live streaming and delegated receipts, persistence redaction, checkpoint inventory, process/filesystem tools, managed agent groups, approval brokers, normalized run handles and completion checks. If a package index does not yet contain 0.8.1, ProtoLink must be published there before ProtoAgent 0.3.0 can be installed from that index.
Build The CLI
cargo build --locked --manifest-path cli/Cargo.toml
For release builds:
cargo build --release --locked --manifest-path cli/Cargo.toml
The crate name is proto-cli. You can run it through Cargo while developing:
cargo run --locked --manifest-path cli/Cargo.toml -- start
Many user-facing examples use proto-cli or protoagent as the installed
binary name. During development, replace that with the cargo run form above.
Check component versions with:
cargo run --locked --manifest-path cli/Cargo.toml -- version
Install The Docs Site
The Docusaurus site lives in docs/.
cd docs
npm install
npm run start
The site is configured to serve the docs from docs/content/, not from the
default nested docs/docs/ path. That keeps documentation pages separate from
site configuration and styling.
Optional Local Model Setup
Ollama is the default local provider. If you use Ollama, install and pull a code model first:
ollama pull qwen2.5-coder:7b
Then select it in ProtoAgent:
cargo run --locked --manifest-path cli/Cargo.toml -- model
You can also use the TUI /model command after starting the fullscreen UI.
Environment Isolation
By default, local config and state live under ~/.protoagent. For repeatable
tests or demos, point ProtoAgent at a disposable config directory:
export PROTOAGENT_CONFIG_DIR=/tmp/protoagent-demo
This redirects provider config, project config, session summaries, Context Loom indexes, ProtoLink conversation storage, and trace output.