Getting Started

Prerequisites

  • Node.js 22+
  • An API key for at least one supported LLM provider (OpenAI, Anthropic, Google)

Installation

npm install -g armament

Or clone and build from source:

git clone https://github.com/rtruitt/armament
cd armament
npm install && npm run build
npm link

Initial Setup

Run the setup wizard to configure your first provider:

armament init

This creates ~/.armament/ with default configuration:

~/.armament/
├── config.json          # Main configuration (JSON)
├── themes/              # Custom theme definitions
├── drift/               # File-based snapshot archive
├── channels/            # Per-channel state and workspace
└── sessions/            # Session checkpoints

Your First Session

Launch armament:

armament

You’ll see the boot sequence — gradient logo, provider verification, MCP server connections, model loading. Once the prompt appears:

[session-01] ▸

You’re ready. Try these commands:

/models                    # List available models
/agents                    # Show active agents
/route task=hello model=*  # Route a task to best-fit model
/theme ice                 # Switch to ice theme

Key Concepts

Sessions

Every armament launch creates a session with its own ID, checkpoint history, and budget tracking. Sessions can be paused, resumed, and recovered from crashes.

Agents

Agents are persistent AI workers within a session. Each agent has a model assignment, context window, and task queue. Spin up multiple agents for parallel work.

Routing

The routing engine selects the optimal model for each task based on complexity analysis, cost constraints, and fallback rules you define.

Web UI

Launch armament with the web interface:

arma --web

This starts a web server at http://localhost:3584 with:

  • 💬 Chat — IRC-style channels for talking to agents
  • 🔄 Flows — Visual workflow builder with React Flow, drag-and-drop nodes, JSON storage
  • ▶️ Running — Live execution dashboard showing orchestrator/worker cards, parallel workers in grid, real-time messages
  • Right sidebar — Agent status, tools with toggle switches, workspace file tree, notes, drift status
  • Permissions — Workspace sandbox with allow/deny approval for external file access, god mode toggle

See Flow Builder for details on the visual workflow editor.

Next Steps