zerostack: Minimal Rust Coding Agent Setup Guide

TL;DR

TL;DR: zerostack is a minimal coding agent written in Rust — ~13k lines of code, 16MB RAM footprint, and 12.9MB binary. It supports OpenAI, Anthropic, Gemini, OpenRouter, Ollama, and custom providers with five permission modes, session management, and MCP server integration.

Source and Accuracy Notes

Based on the official zerostack repository and its documentation as of June 2026. Config details sourced from the repo’s CONFIG.md.

What Is zerostack?

zerostack is a terminal-based AI coding agent designed for developers who want a fast, lightweight alternative to heavier Node.js-based coding assistants. Written in Rust, it draws inspiration from pi and opencode but strips away the bloat — the entire codebase is approximately 13,000 lines.

The agent runs directly in your terminal via a crossterm-based TUI with markdown rendering, mouse selection, scrollback, and reasoning visibility toggles. It’s built for developers who care about resource efficiency without sacrificing capability.

Key Architecture Decisions

• Rust native binary: Single 12.9MB executable, no runtime dependency
• Memory-first design: Averages 16MB RAM vs 300MB+ for Node.js-based alternatives
• CPU-efficient: 0% idle, ~1.5% during tool use on modest hardware
• Multi-provider: OpenRouter (default), OpenAI, Anthropic, Gemini, Ollama, and custom endpoints

Repo-Specific Setup Workflow

Prerequisites

• Rust toolchain (Cargo) installed
• Git
• An API key for at least one provider (OpenRouter recommended for getting started)

Step 1: Install zerostack

# Default install — MCP, loop, and git-worktree included
cargo install zerostack

# With ACP (Agent Communication Protocol) support for editor integration
cargo install zerostack --features acp

Pre-built binaries are also available on GitHub Releases.

Step 2: Configure Your Provider

# OpenRouter is the default provider
export OPENROUTER_API_KEY="your-key-here"

# Or use other providers:
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

Step 3: Start a Session

# Interactive session (default prompt: code)
zerostack

# Monochrome TUI for minimal terminals
zerostack --no-color

# One-shot: run a single prompt and exit
zerostack -p "Explain this project"

# Continue your last session
zerostack -c

# Pick a specific model
zerostack --provider openrouter --model deepseek/deepseek-v4-flash

Step 4: Explore Configuration

Run /prompt autoconfig inside zerostack to launch an interactive documentation agent that helps you navigate settings, permission rules, and MCP server configuration.

Optional: Sandbox Mode

Install bubblewrap for isolated command execution:

# Debian/Ubuntu
apt install bubblewrap

# Fedora
dnf install bubblewrap

# Arch
pacman -S bubblewrap

Then launch with zerostack --sandbox. zerostack also supports zerobox as an alternative sandbox backend.

Deeper Analysis

Permission System

zerostack ships with five configurable permission modes and per-tool pattern matching. You can build allowlists per session, control tool access granularly, and configure how permission rules apply across modes. This gives you defense-in-depth that heavier agents struggle to match — you’re not just hoping the model behaves, you’re enforcing what it can touch.

Prompts System

The built-in prompts system lets you switch the agent’s behavior at runtime without managing external skill files. Available modes include code (default, full tool access with TDD workflow), plan (planning-only), review, debug, and others. Each prompt changes the agent’s tone, tool access, and output style — analogous to loading a skill but built into the binary.

Session Management

zerostack supports save, load, resume, and auto-compaction of sessions. When you approach the context window limit, it automatically compacts conversation history so you can keep working without losing state. Combined with persistent memory (a global MEMORY.md plus per-project daily logs), the agent maintains continuity across sessions.

ACP and Editor Integration

The optional ACP (Agent Communication Protocol) feature lets editors like Zed connect to zerostack as an agent backend. This means you can use zerostack from within your editor rather than a separate terminal.

Integrated Tools

• Exa search: WebFetch and WebSearch capabilities for live internet lookups
• Ralph Wiggum loops: Looping constructs for long-horizon, multi-step tasks
• Git Worktrees: Use /worktree to move the agent between git worktrees
• MCP: Optional compile-time feature for connecting MCP servers

Practical Evaluation Checklist

• Low resource footprint: ~16MB RAM vs hundreds of MB for alternatives
• Rust-native tooling: integrates naturally with Rust projects
• Permission controls: five modes with per-tool rules, not just a yes/no toggle
• Provider flexibility: switch between OpenAI, Anthropic, Gemini, Ollama, and custom endpoints
• Session continuity: save/resume with auto-compaction
• Sandbox support: bubblewrap and zerobox backends for safe execution
• ACP support: connect from Zed and potentially other editors

Security Notes

• The sandbox feature (bubblewrap/zerobox) is optional but strongly recommended for untrusted code execution
• Permission modes default to interactive granting — each tool invocation can be approved or denied
• API keys are read from environment variables, never stored in config files
• The project is open-source (~13k LoC): you can audit every line of agent behavior
• No telemetry or phone-home behavior noted in the source

FAQ

Q: How does zerostack compare to Claude Code or Codex CLI? A: zerostack uses ~16MB RAM versus 300-700MB for Node.js-based alternatives. It supports multiple providers (not locked to one API), and its permission system is more granular than most competitors. However, it’s a newer project with a smaller community.

Q: Can I use my own LLM provider? A: Yes. zerostack supports custom providers via its config file, in addition to OpenRouter, OpenAI, Anthropic, Gemini, and Ollama.

Q: Does it work on Windows? A: Windows support is untested but the project welcomes bug reports and contributions. The TUI uses crossterm which is cross-platform.

Q: What’s the learning curve switching from a GUI coding agent? A: The TUI is keyboard-driven with markdown rendering. /prompt autoconfig walks you through configuration. If you’re comfortable with terminal tools like vim or helix, you’ll pick it up quickly.

Context Window Efficiency

zerostack’s auto-compaction strategy deserves special attention. When the conversation approaches the context window limit, it doesn’t simply truncate — it summarizes earlier exchanges, preserves key decisions and code artifacts, and maintains the agent’s working memory. This means you can run multi-hour sessions without losing context or hitting token limits. Combined with the persistent memory system (global MEMORY.md plus per-project daily logs), zerostack provides continuity that heavier agents often lack.

Community and Ecosystem

The project maintains a Matrix chatroom for collaboration and support. Despite being a solo developer effort, the codebase is clean, well-organized, and approachable for contributors — roughly 13k lines of code means you can read the entire agent in an afternoon. Pre-built binaries on GitHub Releases make it accessible to developers who don’t have Rust installed.

Conclusion

zerostack delivers what heavy AI coding agents can’t: lean resource usage, provider flexibility, and fine-grained control — all in a 12.9MB Rust binary. It’s ideal for developers on resource-constrained machines, those who want auditable tool behavior, or anyone tired of agents that consume gigabytes of RAM just to suggest a refactor. The prompts system and permission modes make it production-viable out of the box.