Skip to content
APX

Quick start

This walkthrough takes you from an empty project to a running agent in a few minutes.

  1. Initialize a project. In any directory you want APX to manage:

    Terminal window
    apx init --name "My Project"

    This creates the .apc/ folder and an AGENTS.md. See Projects for what lands on disk.

  2. Add an agent. Give it a slug, a role, and a model:

    Terminal window
    apx agent add sofia --role "backend reviewer" --model ollama:llama3.2:3b
    apx 
    $ apx agent add sofia --role 'backend reviewer' --model ollama:llama3.2:3b
Added agent sofia
Role: backend reviewer
Model: ollama:llama3.2:3b
✓ wrote .apc/agents/sofia.md
✓ created runtime dir .apc/runtime/agents/sofia/
• rebuilt project #1 (5 agents)
    apx agent add creating the sofia agent and writing .apc/agents/sofia.md

  3. Run the agent through a full runtime. This spawns an external coding CLI (here, Claude Code) with the agent’s system prompt injected:

    Terminal window
    apx run sofia --runtime claude-code "Review the open PRs and summarize them"

    Prefer a quick, one-shot LLM answer instead? Use exec:

    Terminal window
    apx exec sofia "What is my role in this project?"

  4. Watch what’s happening. Tail the message log across all channels:

    Terminal window
    apx messages tail
    apx 
    $ apx messages tail
2026-06-14 09:31:02  → runtime    sofia: spawned claude-code (exit 0, 4.2s)
2026-06-14 09:31:06  ← user       alex: What is my role in this project?
2026-06-14 09:31:08  → agent      sofia: I'm the backend reviewer — I check PRs
2026-06-14 09:32:14  → super-agent roby: routed 1 task to sofia
• 4 messages · channel: all
    apx messages tail showing runtime and exec activity with actor types

The interactive wizard

Section titled “The interactive wizard”

Prefer to be guided? apx setup walks you through provider → model → channels → daemon in one flow:

Terminal window
apx setup
apx 
$ apx setup
  Setup Wizard — configure daemon, model, and channels

Enable super-agent? [Y/n] y

AI Provider:
  1. Anthropic (Claude)
  2. OpenAI (GPT)
  3. Ollama (local / self-hosted)
  4. Gemini (Google)

Choose [1-4]: 1
Anthropic API key (sk-ant-...): ••••••••••••

Model:
  1. claude-sonnet-4-5
  2. claude-haiku-4-5
  3. claude-opus-4-5

Choose [1-4]: 1
› claude-sonnet-4-5

✓ Config saved to ~/.apx/config.json
Starting daemon... running ✓
✅ APX is ready! — http://127.0.0.1:7430
apx setup wizard: choosing a provider and model

Next

Section titled “Next”