Self-hosting agent-zero

agent-zero runs anywhere you can run Python or Node. You don't need Vibe Studio, session-manager, or AppMint to use the agent — those bring the workspace UI, the deploy pipeline, and the discovery integration, but the agent itself is a CLI that takes a model and an API key.

This page focuses on a-mini because it's the easier starting point. a-full self-hosting is similar — clone, install Node deps, run.

a-mini quickstart

git clone <agent-zero-repo>
cd agent-zero/a-mini
pip install -r requirements.txt

export ANTHROPIC_API_KEY=sk-ant-...
python nano_claude.py

That's it. The REPL drops you into an Anthropic-backed agent with the 18 built-in tools, memory, skills, and sub-agents. Type a prompt or /help for slash commands.

Dependencies

a-mini/requirements.txt lists:

• anthropic — the official SDK. Used when the model is Anthropic.
• openai — for OpenAI-compatible providers (OpenAI, Ollama, LM Studio, vLLM, Kimi, Qwen, Zhipu, DeepSeek, custom).
• httpx — HTTP client for the providers that need direct REST.
• rich — terminal rendering (diff view, syntax highlighting).

That's the whole runtime. ~5000 lines of Python, four dependencies.

Choosing a model

a-mini supports a long list of providers via providers.py. The model name decides the provider:

# Anthropic
python nano_claude.py --model claude-opus-4-6
python nano_claude.py --model claude-haiku-4-5-20251001

# OpenAI
python nano_claude.py --model gpt-4o
python nano_claude.py --model o3-mini

# Gemini
export GEMINI_API_KEY=AIza...
python nano_claude.py --model gemini/gemini-2.0-flash

# Local via Ollama (no key needed)
python nano_claude.py --model ollama/qwen2.5-coder

# Self-hosted vLLM
export CUSTOM_BASE_URL=http://localhost:8000/v1
export CUSTOM_API_KEY=none
python nano_claude.py --model custom/Qwen/Qwen2.5-Coder-7B-Instruct

Full provider list is in the a-mini README.

Configuration file

API keys, default model, permission mode, and other settings persist to ~/.nano_claude/config.json:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 8192,
  "permission_mode": "auto",
  "verbose": false,
  "thinking": false,
  "anthropic_api_key": "sk-ant-...",
  "openai_api_key": "sk-..."
}

Set values via the REPL:

/config anthropic_api_key=sk-ant-...
/config model=claude-sonnet-4-6
/config permission_mode=auto

Or edit the JSON directly. Both work.

Permission modes

Three modes:

• auto (default) — read-only ops auto-approve, mutations prompt.
• accept-all — never prompts. Use in CI / scripts only.
• manual — prompts before everything.

python nano_claude.py --accept-all --print "Write a Python fibonacci function"

Non-interactive mode

--print disables the REPL — agent runs the prompt and exits. Useful in scripts:

python nano_claude.py --print "Explain the diff between branches main and feature-x" \
  --accept-all -m gpt-4o-mini

Memory and skills paths

Memory: ~/.nano_claude/memory/ (user) and ./.nano_claude/memory/ (project, current cwd).

Skills: ~/.nano_claude/skills/ (user) and ./.nano_claude/skills/ (project).

Sessions: ~/.nano_claude/sessions/ — saved via /save, restored via /load.

You can override with environment variables if you need to relocate (check config.py for the variable names — most users don't need this).

CLAUDE.md

a-mini auto-loads a CLAUDE.md in the cwd (and in ~/.claude/ for global rules). It's injected into the system prompt so the model has persistent context about your project. See Working with the agent for what to put in it.

Self-hosting a-full

a-full lives at agent-zero/a-full/. It's a TypeScript monorepo with build tooling. Quick start:

cd agent-zero/a-full
npm install
npm run build
node dist/cli.js   # or whatever the entry point name is in your version

Check the package.json for the canonical entry. a-full has more features — ink-based terminal UI, voice input, dialog launchers, output styles, more providers — and consequently more code paths to debug.

If you're building a custom workspace UI, a-full is the runtime to integrate with. session-manager already does this; you'd be replicating its bridge.service.ts pattern.

Running agent-zero against AppMint

Set the AppMint env vars from anywhere — there's no hard dependency on session-manager:

export APPMINT_API_URL=https://appengine.appmint.io
export APPMINT_ORG_ID=your-org-id
export APPMINT_TOKEN=$(curl -s -X POST $APPMINT_API_URL/profile/user/signin \
  -H "orgid: $APPMINT_ORG_ID" \
  -d '{"email":"...","password":"..."}' | jq -r .token)

python nano_claude.py

The agent's discovery-first behaviour kicks in automatically — curl $APPMINT_API_URL/discover/... works because APPMINT_API_URL is set.

For staff-only operations, signin via /profile/user/signin; for customer-facing apps, use /profile/customer/signin and pass the resulting token. See Actors and auth.

Running in CI

python nano_claude.py --print --accept-all \
  --model claude-haiku-4-5-20251001 \
  "Review the diff between $BASE and $HEAD and report Critical / Warning / Suggestion findings."

The --print flag emits the final answer to stdout, exits non-zero if the agent errors. Pipe into your CI step.

Limitations of self-hosted

• No deploy pipeline. SpinForge integration lives in session-manager. To deploy from a self-hosted setup, build your own pipeline that uses SpinForge's partner API.
• No workspace UI. You're working in a terminal. If you want an editor, drive a-full from your own UI.
• No discovery sync. The .vibe/appmint-api.md cached snapshot is only created by session-manager. Live discovery via curl works either way.
• No planner. The planner UI is a Vibe Studio feature; the data file (.vibe/planner.json) is just JSON the agent can edit, but you won't get the kanban view.

Upgrades

a-mini's versions are listed in the README's News section. Upgrade in place:

git pull
pip install -r requirements.txt

Check the changelog for breaking changes — the tool registry shape, the provider API, and the memory schema have all evolved across versions.