AGENT_BACKEND environment variable before starting the gateway.
Backend comparison
| Feature | Pi | Codex | Local |
|---|---|---|---|
| Tool use | Full (native Pi tools) | Full (shell and file tools via Codex) | None — conversational only |
| Nuggets memory tools | nuggets, createNote, addLink, editNote, searchNotes | Prompted via nuggets recall / nuggets remember CLI | Not available |
| Scheduling | schedule tool (Pi extension) | Writes to .gateway/cron/requests.jsonl | Not available |
| Memory reflection | reflectAndCleanMemory tool (Pi extension) | Prompted via Codex shell tools | Not available |
| Skills delivery | Passed as real Pi --skill files | Skills catalog in prompt; files read on demand | Skill contents inlined into system prompt |
| Session persistence | Pi session files (JSONL, per conversation) | Codex thread ID (per conversation) | Chat history JSON (last 40 messages) |
| Provider selection | AGENT_PROVIDER + AGENT_MODEL | Model via AGENT_MODEL, optional OSS flag | LOCAL_MODEL_PROVIDER + LOCAL_MODEL_BASE_URL |
| Conversational only | No | No | Yes |
Environment variables
Selecting the backend
Selecting the provider and model (Pi and Codex)
AGENT_PROVIDER and AGENT_MODEL are read by the Pi backend directly. The Codex backend uses AGENT_MODEL when you want to pass a specific model to codex exec. The Local backend ignores AGENT_PROVIDER entirely and uses LOCAL_MODEL_PROVIDER instead.
PI_PROVIDER and PI_MODEL are kept for legacy compatibility. When set, they are used as fallbacks for AGENT_PROVIDER and AGENT_MODEL respectively.When to choose each backend
Pi — full tool use with native memory integration
Pi — full tool use with native memory integration
Choose Pi when you want the richest memory and tool experience. Pi runs as a persistent subprocess per conversation, with the full Nuggets extension loaded. The agent can directly call
nuggets, createNote, addLink, editNote, searchNotes, schedule, and reflectAndCleanMemory as structured tools. Sessions resume across restarts.Best for: personal assistants, long-running projects, anyone who wants deep memory integration and scheduling.Codex — full tool use via shell and file access
Codex — full tool use via shell and file access
Choose Codex when you want a code-oriented agent that can read, write, and execute files. Codex receives the Nuggets recall-first behavior as prompt instructions and can invoke the
nuggets CLI directly. The skills catalog is included in the prompt so Codex can read any SKILL.md file on demand.Best for: software development tasks, automation, users who are already familiar with Codex.Local — conversational model with no external dependencies
Local — conversational model with no external dependencies
Choose Local when you want to run everything on-device with no cloud API keys. The backend connects directly to an OpenAI-compatible server such as Ollama or MLX. There are no tool calls — the model converses naturally, and active skill contents are inlined into the system prompt.Best for: privacy-first setups, offline use, experimentation with local models.
Backend pages
Pi
Full tool use with native Nuggets memory extensions, session pools, and Pi skill files.
Codex
Shell and file access via Codex CLI with recall-first memory prompting.
Local
Conversational-only backend for Ollama, MLX, or any OpenAI-compatible local server.