Kodacity [Matrix] — Help & Documentation

Kodacity [Matrix] is an AI agent management platform. It lets you build, publish, install, and run AI agents as Docker containers — then wire them into swarms, group swarms into networks, and operate the whole thing from a desktop app or the matrix CLI.

The desktop app and the CLI share the same state directory (~/.matrix/), so anything you do in one is instantly visible in the other.

Where to start

New to the platform? Read Getting Started, then skim Core Concepts. Everything else is reference material you can dip into when you need it.

Contents

Basics

The desktop app (GUI)

The CLI

Guides

Licensing

Kodacity [Matrix] is free for personal use and teams of up to 5 people. For larger teams and enterprise support, contact redpill@kodacity.ai.

Getting Started

← Back to index

Requirements

• A container engine. Docker Desktop, Docker Engine, Podman, Colima, or OrbStack. The engine socket is configurable, so you are not tied to Docker Desktop.
• An AI provider. An API key for Anthropic, OpenAI, or Google — or a local model via Ollama, LM Studio, or any OpenAI-compatible endpoint. Keys are yours and stay on your machine.
• For the CLI: Node.js ≥ 18.
• OS: macOS 13+ (Apple Silicon), Windows 10/11 (x64), or Linux (x64).

Install

Desktop app — download the installer for your platform from the download page.

CLI only:

Not in v2.0.0. The standalone matrix CLI is finished and in testing; the npm package name is reserved and the release will follow shortly. Until then, use the desktop app.

npm install -g kodacity

This installs the matrix binary globally. The app and the CLI can be installed side by side; they share all state.

First run: configure a provider

In the desktop app, open Source → Settings and paste your API key(s), then pick a default model.

From the CLI:

matrix config set anthropic-key sk-ant-…
matrix config set model claude-sonnet-4-6

Using a local model instead? Register the provider first:

matrix provider add        # probes Ollama / LM Studio / llama.cpp and lets you pick a model
matrix provider default    # set the global default model

Run your first agent

The fastest path is an agent someone has already published:

# Find one
matrix search coding-assistant

# Install it (any OCI registry works)
matrix install ghcr.io/me/coding-agent:latest

# Run it against a project folder
matrix run coding-agent ~/projects/myapp

The agent starts in an isolated container with your workspace mounted at /workspace and your provider credentials injected automatically. Output streams to your terminal; type into it to answer the agent's questions.

In the desktop app the same flow is: Matrix → Bureau (find & install) → Operator → Jack-In (assign an objective and watch it run).

Or build your own in five minutes

mkdir my-agent && cd my-agent
matrix build            # no Matrixfile? one is scaffolded for you
# edit the Matrixfile — model, tools, system prompt
matrix build            # builds a versioned OCI image
matrix run my-agent ~/some/project

See Building Agents for the full Matrixfile format and the visual Spawn composer.

What's next

• Wire several agents into a team: Orchestration
• Run agents automatically on a schedule: Automation
• Install a whole pre-built company for your industry: Industry Packs
• Learn the app surface: GUI Overview

Where everything lives

All persistent state is in ~/.matrix/ — installed agents, registries, run history, schedules, credentials. The full file list is in the CLI Reference.

Core Concepts

← Back to index

The platform has a small number of building blocks that compose upward: agents form swarms, swarms form networks, and everything an agent does is recorded, budgeted, and verifiable. This page defines each concept once; the guides link back here.

Agent

An agent is a packaged AI worker: a model hint, a system prompt, a set of tools (MCP servers), skills, and permissions — built into a standard OCI (Docker) image. Because it's an image, an agent has a version, can be pushed to any registry, installed anywhere, rolled back, and shared. Agent images are identified by dev.kodacity.* OCI labels (name, version, tools, skills, transport, permissions, model hint).

At run time the agent gets a fresh, isolated container. Your workspace directory is bind-mounted at /workspace; provider credentials and the resolved model are injected as environment variables. Nothing is baked into the image, so the same image runs with anyone's keys and any provider.

Run

Every container launch is a run. Runs are recorded in the run log (~/.matrix/run-log.json, last 500 entries) with agent name, workspace, start/end times, exit status, and — when launched from the desktop app — exact input/output token counts captured by a transparent local proxy. The Uplink view and matrix uplink show the history.

Swarm

A swarm is a team of installed agents wired together. One member is the entry point; delegation lines define who may hand work to whom. Swarm members mount their own persistent memory, so a member gets better at its role across runs.

Hardline

The Hardline is a swarm's (or network's) communication contract: topology (star, mesh, or pipeline), channel (inbox or operator-relay), max rounds, broadcast on/off, and human-in-loop on/off. Edit it in the Hardline view or with matrix swarm hardline / matrix network hardline.

Network

A network groups swarms into an isolated company: a shared workspace, a shared knowledge base, its own Missions board, a budget pool, and optionally an accountable operator (a named person forming the audit boundary). One swarm is the lead. Run the entire company with a single objective:

matrix operator run --network acme-corp --objective "…"

Missions

Each network has a task board (kanban + backlog). Agents automatically pull open tasks when the network runs; a completed task links to the run that did the work. Agent-proposed features queue as proposals until you approve them — agents don't expand their own scope.

Objective / Assignment

The unit of work you hand to an agent, swarm, or network from the Operator (Jack-In) view or matrix operator run. Saved, reusable objectives for one-off contractor agents are called Patch assignments.

Loop

A run mode where the target iterates on an objective until a stop condition is met: a max-iteration ceiling, a spend budget, a passing evaluation, or per-iteration human approval. Loops can attach a verifier (below).

Verifier

An independent judge attached to a loop run. It scores each iteration against a rubric and can run execution checks against the staged output — either commands you specify or checks the verifier proposes itself after inspecting the file tree. Panels of N-of-M judges are supported, including judges on a different provider than the workers (no model marks its own homework). The delivery gate controls promotion of the result: none, verifier, human, or both.

Loadout (knowledge pack)

A versioned, reusable bundle of knowledge sources. Author loadouts in the Loadouts view, assign them to agents or swarms in the Armoury. CLI: matrix loadout … and matrix armoury ….

Memory & Lessons

Agents keep persistent global memory across runs (matrix memory list|show|edit|clear). Lessons are outcome-tagged records distilled from finished runs and fed back into future attempts, so failures aren't repeated and wins are.

Wiretap

The platform's message bus tap: every inter-agent and swarm message is observable in a live feed with kind/network/swarm filters. Nothing moves between agents off the record.

Bank, Identity & Budget

The Bank view is the spend ledger and identity surface. Identity mode is Local or Entra — in Entra mode agents get real Entra ID user accounts, mirroring a worker's access for permissioning, group membership, and revocation. Budgets support per-agent caps, per-swarm caps, and network-wide pools, with warn or hard (auto-stop) enforcement.

Exits

Controlled gateways from a sandboxed agent to a real external system (GitHub, GitLab, Jira, Slack, AWS, Kubernetes, Postgres, GitHub Actions). Each exit defines the allowed hosts, the CLI tooling baked in, per-verb policy rules (allow / approval / deny), and how credentials are supplied — the Keymaker mints short-lived credentials so agents never hold long-lived secrets. See Governance & Security.

Bureau & The Matrix registry

The Bureau is the registry browser. It searches the built-in Matrix registry and any OCI registry you've added, and installs agents or skill packs with one click. CLI: matrix bureau, matrix search, matrix install.

Pack

A bundle of multiple agents distributed as a single OCI artifact (matrix pack import <ref>). Industry packs go further: a role matrix compiled into a full company — agents, swarms, a network, seed missions, and eval suites. See Industry Packs.

Recruits

The bundled starter library: prebuilt agents and department swarms you can build and install with one click (Recruits view, matrix recruits …).

Déjà Vu

Scheduled and triggered runs: cron expressions, file-watch, or webhooks. Schedules persist across restarts. See Automation.

Black Site

Opt-in Kubernetes runtime. Deploy an agent or a swarm to a cluster, scale replicas, read logs, and tear down — same observability as local runs. See Source & Grid.

Image trust

Digest pinning for agent images, verified at container start. Policy is off, warn, or enforce (matrix images …). A pinned image that changes upstream won't silently run.

GUI Overview

← Back to index

The desktop app (Electron, macOS/Windows/Linux) is the visual surface over the same state the CLI uses.

Layout

┌──────────────────────────────────────────────────────────────────────┐
│ TopBar: project picker · status · model selector · network filter    │
├────┬──────────────────────────────────────────────┬──────────────────┤
│    │                                              │                  │
│ R  │           Main canvas                        │   Chat panel     │
│ a  │  (the active view)                           │  (Brief / Steer  │
│ i  │                                              │   / Ask)         │
│ l  │                                              │                  │
│    ├──────────────────────────────────────────────┴──────────────────┤
│    │ Terminal drawer (collapsible) — log stream + agent filter       │
└────┴──────────────────────────────────────────────────────────────────┘

• Top bar — project/workspace picker, engine status, model selector, and the network filter that scopes most views (Agents, Bank, Missions…) to one network or all.
• Activity rail (left) — the five modes, each an accordion of views.
• Main canvas — the active view.
• Chat panel (right) — brief Claude-style chat against your current context; from a chat you can promote "do this for real" into a Patch assignment.
• Terminal drawer (bottom) — live log stream with a per-agent filter.

The five modes

Each mode has its own page in these docs: Operator · Matrix · Sentinel · Source & Grid.

The CLI's interactive REPL mirrors this rail 1:1 (it labels Sentinel as MONITOR). Anything you can click has a matrix command — view pages note the equivalents.

Keyboard shortcuts

On Windows/Linux use Ctrl in place of ⌘.

App ↔ CLI parity

The app and matrix share ~/.matrix/:

• matrix install … → the agent appears in Matrix → Agents instantly.
• Launch from the app → it shows in matrix ps.
• matrix uplink and the Uplink view show the same history.

One difference: the app stores API keys with OS keychain encryption; the CLI stores them in a 0600 plaintext file. If you use both, prefer the app's Settings for keys.

Operator Mode

← Back to index · GUI Overview

Operator mode is where work gets assigned, watched, and steered. Four views: Jack-In, Missions, Patch, and Surf.

Jack-In (the cockpit)

The default view. Left: a run rail of running and recent runs with network/status filters. Right: the live run pane.

Starting a run

Click New assignment (or arrive from Agents/Swarms/Network with the target pre-filled). The assignment modal lets you set:

• Target — a network (whole company), a swarm (team), or a single agent.
• Objective — what you want done.
• Workspace — the directory mounted at /workspace.
• Model — override the model for this run.
• Pull open tasks — for network runs, agents also pull open Missions tasks from the board.
• Loop — iterate until a stop condition is met (max iterations, spend budget, passing eval, or per-iteration approval). Loops can attach a verifier — see Orchestration.

CLI equivalent:

matrix operator run --network acme-corp --objective "…" \
  [--loop --max-iterations 5 --budget 10 --stop-on-eval --approve-each]

The run pane

Tabs across the top of an open run:

Steering mid-run

Type into the composer while a run is live to steer it — your message is queued and delivered to the running member at the next step boundary. Use it to redirect, add constraints, or answer questions without stopping the run. Stop cancels the run.

The header switches between Chat / Operator / Workspace so you can flip between conversation, cockpit, and files without losing the run.

Missions

The per-network task board — select a network in the top bar first.

• Board — five kanban columns; drag or use the detail modal to move status. Cards show priority, feature chip, and key.
• Backlog — the same tasks as a filterable list. Agent-proposed tasks fold into the backlog until you approve them.
• New task — title, description, priority (low/medium/high), feature.
• Run open tasks — jumps to Jack-In with the network targeted and pull-tasks enabled.
• Watch run — a claimed (in-progress) task links to its live run; task output opens in Surf.

CLI: matrix missions list|add|done|rm <network> …

Patch

Saved, reusable objectives for contractor agents — work you fire repeatedly without rebuilding the brief.

• The rail lists saved assignments; selecting one shows its objective and run history.
• Fire launches it and drops you into Jack-In.
• New / Edit manage the assignment (target agent, objective, workspace).
• Chat panel hand-off: from a chat, "do this for real" opens a new Patch assignment prefilled.

CLI: matrix patch list|show|rm

Surf

A file explorer over run outputs and network workspaces.

• Workspace dropdown across your roots; Open folder adds another.
• Lazy directory tree with git status tags (A/M) and a code viewer.
• Deep links land here: a run's Output tab or a mission's output opens the exact file.

Matrix Mode

← Back to index · GUI Overview

Matrix mode is where the workforce is built: find agents, compose new ones, wire teams, and arm them with knowledge.

Bureau

The registry browser.

• Search (debounced) across the default Matrix registry, or switch to any registry you've configured.
• Filters — category sidebar plus a "Verified publishers" toggle.
• Featured row + result list; Install pulls the image and registers it locally in one click.

CLI: matrix bureau, matrix bureau versions <name>, matrix search <query>, matrix install <image>

Agents

Your installed-agent library.

• List or grid, with search and role/status filters. The top-bar network filter scopes what you see.
• Per-agent actions: Launch (routes to Jack-In with the assignment modal pre-targeted), Program (opens Spawn seeded with the agent's manifest so you can iterate on it), Uninstall.
• A Docker banner appears if the container engine is unreachable, with a retry.

CLI: matrix list, matrix info <name>, matrix update [name], matrix remove <name>

Spawn

The visual agent composer — numbered steps with a live Matrixfile preview that updates as you configure:

1. Identity — name, version, description.
2. Base — the base Docker image.
3. Tools — search and pick MCP servers.
4. Skills — search and pick skill packs.
5. Model — the model hint (overridable at run time).
6. Permissions — network on/off, filesystem read-write/read-only.
7. Prompt — the system prompt.

Build streams the Docker build log live; the result lands in your library ready to run or publish. See Building Agents for the file formats behind this.

CLI: matrix spawn scaffold|search-mcp|search-skills|dockerfile|build

Swarms

The team list. Each row is a swarm — search and filter by topology.

• Launch → Jack-In targeting the swarm.
• Hardline opens the comms editor as a modal (topology cards, channel, broadcast, rounds, human-in-loop).
• New swarm → the Hardline page to wire it up.

CLI: matrix swarm list|show|new|add-member|remove-member|entry|line|delete

Hardline

The full-page communication editor: pick a swarm in the rail, then configure topology (star / mesh / pipeline), channel (inbox / operator-relay), max rounds, broadcast, and human-in-loop. Details on what these mean: Orchestration.

CLI: matrix hardline <name> (alias of matrix swarm hardline <name>)

Armoury

Assign knowledge loadouts to agents and swarms.

• Loadout cards/rows with search and category filter.
• Manage opens the assignment modal — switch between Agents and Swarms, toggle each row Assigned/Off. Assignments are {slug, version} references, so upgrading a loadout is explicit.

CLI: matrix armoury show|assign|unassign|clear [agent]

Loadouts

Author and grow the knowledge packs themselves.

• Create — name, tags, description, plus source rows (kind + reference), repeatable.
• Grow a loadout over time with more sources; versions keep assignments stable.
• Assign from here too (same modal as the Armoury).

CLI: matrix loadout list|show|create|add|delete

Recruits

The bundled starter library, in three sections:

• Enterprises — full industry packs (whole companies). See Industry Packs.
• Swarms — department swarms; importing builds any missing member agents automatically.
• Agents — individual starter agents, built and installed with one click.

CLI: matrix recruits list|build|import, matrix industry list|build|install

Sentinel Mode

← Back to index · GUI Overview

Sentinel is the watchtower: dashboards, message traffic, identity and spend, live containers, schedules, and the audit trail. (The CLI's REPL labels this mode MONITOR.)

Bridge

The at-a-glance dashboard and landing view.

• Stat cards — installed agents, runs today, estimated spend today, running now.
• Recent runs — click through to the run console.
• Get set up — a first-run checklist (install an agent, run an objective, profile your machine with the Architect) that ticks itself off as you go.

Wiretap

The god's-eye view of the agent message bus.

• Live feed of every inter-agent and swarm message, newest first (last ~400 kept in view).
• Filters — kind, network, swarm, and free-text search; scope filters appear automatically once traffic carries those scopes.
• Click a row for the full message detail.

Nothing moves between agents without appearing here. CLI: matrix wiretap recent [-n <limit>] (recent traffic; live tailing is an app feature).

Bank

The spend ledger, identity surface, and budget controls.

• Stat cards — spend today, spend in window, enforcement mode, ledger entries.
• Ledger — every run's cost, scoped by the top-bar network filter; scope segs (All / Networks / Swarms / Agents) and time windows (7d / 30d / All). Selecting a row opens the run-cost detail: token in/out boxes, tool usage, cost rollup.
• Breakdown — by network or by agent, computed from the filtered ledger.
• Local-routing savings — how much routing to local models saved versus cloud pricing.
• Set a cap — the budget modal: global default cap, hard/warn enforcement with a warn threshold, and per-network pool, per-swarm, and per-agent caps. Caps are network-scoped.
• Identity — Local or Entra mode. In Entra mode agents hold real Entra ID accounts; see Governance & Security.

CLI: matrix bank status|spend|elevations, matrix budget status|mode|warn-at|set-pool|set-cap

Switchboard

Live container-engine operations, polled every 5 seconds.

• Containers — every matrix-* container with run, target, network, swarm, status, and size; per-row stop, Stop all, and All-networks / All-swarms scope filters.
• Images — agent images with force-remove.
• Volumes — per-volume table (name, driver, size, created) with remove.
• Disk stats — from docker system df.

CLI: matrix ps, matrix stop <id|name>, matrix logs <id|name>

Déjà Vu

Automated triggers — run agents without being at the keyboard.

• Trigger types — cron expression, file-watch on a path, or webhook (you get a local endpoint to POST to).
• Each trigger sets the agent, workspace, and optionally a network scope.
• Per-trigger Run now, enable/disable toggle, and delete; stat chips count each type.
• Schedules persist across app restarts.

Full guide: Automation. CLI: matrix deja-vu list|add|remove|toggle|run

Uplink

The run audit log — every container run ever (last 500), from both the app and the CLI.

• Table of agent, workspace, started, duration, status, and token in/out counts.
• Clicking a run opens the console drawer: the container's log backlog plus a live stream while it runs, with stop and open-in-Surf actions.

CLI: matrix uplink. Note: token counts are only captured for app-launched runs (see Troubleshooting).

Source & Grid

← Back to index · GUI Overview

Source is the root layer — providers, keys, registries, and company structure. Grid is the scale-out section.

Settings (Source)

• Provider keys — Anthropic, OpenAI, Google. Stored with OS keychain encryption (safeStorage), never baked into images, injected into containers only at spawn time.
• Model selection — the global default model.
• Custom providers — register local/OpenAI-compatible endpoints (Ollama, LM Studio, llama.cpp, vLLM…). localhost URLs are rewritten to host.docker.internal so containers can reach the host.
• Registry management — add/remove OCI registries (with tokens/usernames) and set the default for publish.

CLI: matrix config set|get, matrix provider add|list|remove|default, matrix registry list|add|remove|default

Network (Source)

Group swarms into an isolated company. See Core Concepts for what a network is.

• The list shows each network; Board jumps to its Missions, a row click targets it in Jack-In.
• New network — name, display name, description, workspace, standing objective, and optionally an accountable operator (name + email): the named human forming the audit boundary for everything the company does.
• Budget — the network's spend pool and caps (same data as Bank's cap modal).
• Membership and wiring (add swarms, pick the lead, draw lines, hardline) are available from the network detail and the CLI.

CLI: matrix network list|show|new|add-swarm|remove-swarm|lead|hardline|line|details|delete|nuke|path

Run the whole company: matrix operator run --network <name> --objective "…"

Black Site (Grid)

Opt-in Kubernetes runtime for agents and swarms that outgrow your machine.

• Status / enable / disable — the runtime is off by default.
• Mode — local or blacksite; in blacksite mode, launches route to the cluster.
• Cluster — configure the target cluster connection.
• Deploy — an agent or a whole swarm; scale replicas; logs, endpoint, reapply, teardown.
• Deployments appear in the same observability surfaces as local runs.

CLI:

matrix black-site status|enable|disable
matrix black-site mode <local|blacksite>
matrix black-site cluster …
matrix black-site deploy agent <name> | deploy swarm <name>
matrix black-site list|deployment <name>|scale <name> <replicas>
matrix black-site logs <name>|endpoint <name>|reapply <name>|teardown <name>

Terminal (Grid)

An embedded console styled like the run consoles. It currently provides guidance and echoes commands — use the real matrix CLI in your own terminal for full functionality (the app and CLI share all state, so there's nothing the embedded terminal can do that yours can't).

CLI Reference — matrix

← Back to index

Every feature of the platform is available from the terminal. The CLI and the desktop app share ~/.matrix/, so they can be used interchangeably.

Installation

Not in v2.0.0. The standalone matrix CLI is finished and in testing; the npm package name is reserved and the release will follow shortly. Until then, use the desktop app.

npm install -g kodacity

Requires Node ≥ 18 and a running container engine.

Interactive mode (the REPL)

Run matrix with no arguments to open the interactive menu. It mirrors the desktop app's rail 1:1 — same modes, same order (Sentinel appears as MONITOR):

OPERATOR   run · run (loop) · patch · missions · uplink
MATRIX     browse/search/install · agents (list/build/publish/packs) · swarms · skills
MONITOR    wiretap · bank · switchboard (ps/logs) · deja-vu
SOURCE     network (incl. accountable operator) · config · registry · black-site

Every menu action maps to a plain matrix … command, so anything you can do in the menu you can script.

Configuration

API keys and the default model live in ~/.matrix/credentials.json (mode 0600). Other preferences (custom providers, registries) live in ~/.matrix/settings.json.

matrix config set anthropic-key sk-ant-…     # also: openai-key, google-key, model
matrix config get [key]                      # keys are shown masked

Model resolution order when a container spawns:

1. --model flag on the run command
2. matrix config set model … (global)
3. The agent's built-in model hint (baked at build time)
4. Fallback: claude-sonnet-4-6

Local & custom providers

matrix provider add          Probe a local endpoint (Ollama, LM Studio, llama.cpp…) and pick a model
matrix provider list         List configured custom providers
matrix provider remove <id>  Remove one
matrix provider default      Set the global default model

matrix architect profiles your machine and reports which local models it can actually run.

Agent lifecycle

matrix install <image>        Pull and register an agent locally
matrix remove <name>          Stop containers + remove the image
matrix list                   List installed agents               (alias: ls)
matrix update [name]          Pull latest tag (all if omitted)
matrix search <query>         Search registries for agents
matrix info <name>            Full manifest + OCI labels

Runtime

matrix run <name> [workspace]   Spawn a container and stream output
    --env KEY=VAL                 Inject an extra env var (repeatable)
    --model <model>               Override the model for this run
matrix stop <id|name>           Stop a running container
matrix ps                       List running matrix-* containers
matrix logs <id|name>           Fetch log lines (--tail <n>)
matrix attach <id|name>         Attach stdin/stdout interactively
matrix uplink                   Show run history

Build & publish

matrix build [dir]              Build an image from the Matrixfile / agent.build.json
    --increment patch|minor|major   Version bump (default: patch)
matrix publish [image]          Push to the configured registry
    --registry <name>               Target registry
    --tag <tag>                     Additional tag (repeatable)

Matrixfile format and the full build pipeline: Building Agents.

Spawn (composer from the terminal)

matrix spawn scaffold <name>      Write a starter composer-state.json
matrix spawn search-mcp <query>   Search the MCP server registry
matrix spawn search-skills <q>    Search the skills registry
matrix spawn dockerfile <state>   Preview the generated Dockerfile
matrix spawn build <state>        Build from a composer state file

Registry & Bureau

matrix bureau                    Browse the Matrix registry       (alias: matrix matrix)
matrix bureau versions <name>    List published versions
matrix registry list             Configured registries
matrix registry add <url>        Add one (--token, --username)
matrix registry remove <name>    Remove
matrix registry default <name>   Set the default

Swarms

matrix swarm list                       List swarms                    (alias: ls)
matrix swarm show <name>                Members, entry point, hardline
matrix swarm new <name>                 Create a swarm
matrix swarm add-member <name> <agent>  Add an installed agent
matrix swarm remove-member <name> <id>  Remove a member
matrix swarm entry <name> <id>          Set the entry-point member
matrix swarm hardline <name>            Configure comms (topology/channel/rounds/…)
matrix swarm line add <name> <from> <to>    Draw a delegation line
matrix swarm line list|remove …             Manage lines
matrix swarm delete <name>              Delete                         (alias: rm)
matrix swarm path <name>                Print the swarm YAML path

matrix hardline <name> is a top-level alias for matrix swarm hardline <name>.

Networks

matrix network list                              List networks
matrix network show <name>                       Swarms + hardline
matrix network new <name>                        Create               (alias: create)
    [-d, --display <name>] [--description <text>]
    [-w, --workspace <path>] [--objective <text>]
    [--operator <name>] [--operator-email <email>]   Accountable operator (audit boundary)
matrix network add-swarm <name> <swarm> [--id <id>] [--role <role>] [--lead]
matrix network remove-swarm <name> <id>
matrix network lead <name> <id>                  Set the lead swarm
matrix network hardline <name>                   [--topology star|mesh|pipeline]
    [--channel inbox|operator-relay] [--max-rounds <n>]
    [--broadcast|--no-broadcast] [--human-in-loop|--no-human-in-loop]
    [--pipeline-order <ids>]
matrix network line list|add|remove <name> …     Delegation lines between swarms
matrix network details <name>                    Resolved company view
matrix network delete <name> [-f]                Delete (keeps run artifacts)
matrix network nuke <name> [-f]                  Delete + on-disk files
matrix network path <name>                       Print agent-network.yaml path

Operator (assign & run)

matrix operator run
    --network <name> | --swarm <name> | --agent <name>
    -o, --objective <text>
    -w, --workspace <path>
    --model <model>                Model override for entry/solo agent
    --loop                         Iterate until a stop condition
    --max-iterations <n>           Loop: hard ceiling
    --budget <usd>                 Loop: stop at cumulative spend
    --stop-on-eval                 Loop: stop early on a passing check
    --approve-each                 Loop: human approval per iteration

Loop verifiers, N-of-M panels, and delivery gates: Orchestration.

Missions & Patch

matrix missions list <network>
matrix missions add <network> <title> [--priority low|medium|high]
matrix missions done <network> <taskId>
matrix missions rm <network> <taskId>

matrix patch list          Saved contractor assignments
matrix patch show <id>     Assignment + last run
matrix patch rm <id>       Delete

Knowledge — Armoury & Loadouts

matrix armoury show [agent]              An agent's assigned loadouts
matrix armoury assign [agent] [loadout]  Assign
matrix armoury unassign [agent] <slug>   Unassign
matrix armoury clear [agent]             Clear all

matrix loadout list                      (alias: ls)
matrix loadout show <slug>
matrix loadout create <name>
matrix loadout add <slug>                Add sources
matrix loadout delete <slug>             (alias: rm)

Memory

matrix memory list           Agents with persistent global memory
matrix memory show <name>
matrix memory edit <name>
matrix memory clear <name>   (-f to skip confirmation)

Governance — Bank, Budget, Wiretap, Images

matrix bank status [network]      Identity mode + budget enforcement
matrix bank spend <agent>         Spend rollup for an agent
matrix bank elevations [agent]    JIT access elevations

matrix budget status [network]    Enforcement mode + spend vs caps
matrix budget mode <warn|hard>    Warn only, or hard auto-stop
matrix budget warn-at <pct>       Warn threshold (1–100)
matrix budget set-pool <network> <usd>          Network-wide pool
matrix budget set-cap <network> <agent> <usd>   Per-agent cap (0 = remove)

matrix wiretap recent [-n <limit>]   Recent inter-agent traffic
                                     (live tailing is an app feature)

matrix images list                Trust-pinned images
matrix images trust <image>       Pin at the current digest
matrix images untrust <image>     Remove a pin
matrix images policy [mode]       off | warn | enforce

Déjà Vu (schedules)

matrix deja-vu list                 (alias: ls)
matrix deja-vu add                  Interactive: agent, workspace, trigger
matrix deja-vu remove <id>          (alias: rm)
matrix deja-vu toggle <id>          Enable/disable
matrix deja-vu run <id>             Run now

Webhook triggers print a local endpoint (http://localhost:9119/hook/<id>) you can POST to from CI. Full guide: Automation.

Recruits, Packs & Industry

matrix recruits list                Bundled starter agents + swarms
matrix recruits build <slug>        Build & install one starter agent
matrix recruits import <swarm>      Build members + import a starter swarm

matrix pack list                    Installed packs
matrix pack import <ref>            Install a pack from a registry
matrix pack export <name>           Show pack manifest
matrix pack remove <name>           Remove

matrix industry list                Industry pack definitions
matrix industry build <pack>        Compile → <pack>/dist
matrix industry install <pack>      Compile, optionally gate, install
    [--gate <model>]                    Run eval gate before install
    [--build]                           Also build Docker images

See Industry Packs.

Black Site (Kubernetes)

matrix black-site status|enable|disable
matrix black-site mode <local|blacksite>
matrix black-site cluster …
matrix black-site deploy agent <name> | deploy swarm <name>
matrix black-site list | deployment <name> | scale <name> <replicas>
matrix black-site logs <name> | endpoint <name> | reapply <name> | teardown <name>

Environment variables

Keys set via matrix config set are injected into containers at spawn time. Shell env vars are not automatically forwarded — use --env flags or config set.

Token tracking

App-launched runs capture exact token counts through a transparent local proxy: containers receive a per-run fake key (matrix-proxy-<token>), base URLs point at http://host.docker.internal:18081, the proxy swaps in your real key and taps the response stream's usage field. Real keys never enter the container.

CLI limitation: the proxy lives in the app process, so matrix run injects real keys directly and token counts are not captured — the run entry still records timing and status.

Data files

Relationship to the desktop app

Fully interchangeable: install via CLI → appears in the app; launch in the app → shows in matrix ps; one shared run history. The only difference is key storage — the app uses OS keychain encryption, the CLI a 0600 plaintext file. If you use both, prefer the app's Settings for keys.

Building Agents

← Back to index

There are two ways to build an agent: the visual Spawn composer in the app, and the Matrixfile workflow from the terminal. Both produce the same thing — a versioned OCI image with your agent's configuration baked in as labels.

The Matrixfile

A Matrixfile is the declarative agent configuration — the same idea as a Dockerfile for Docker or a Modelfile for Ollama. Write it once; matrix build compiles it to a Dockerfile and builds the image.

# Matrixfile — Kodacity agent configuration

NAME     my-coding-agent
VERSION  1.2.0

# Base Docker image for the agent runtime
BASE     node:22-slim

# AI model hint (overridable at runtime with --model)
MODEL    claude-sonnet-4-6

# Tools injected at spawn time via MATRIX_TOOLS
TOOL     filesystem
TOOL     bash

# Skill packs embedded in the image
SKILL    git-workflow

# Target registry for matrix publish
REGISTRY ghcr.io/myorg

# Network access inside the container
PERMIT   network false

# System prompt (multiline block — terminated by END on its own line)
PROMPT
You are a senior software engineer working on the /workspace project.
Read existing code before making changes. Ask before large refactors.
END

Directives

Lines starting with # are comments. matrix build auto-increments VERSION and writes it back (--increment patch|minor|major).

Build & publish from the terminal

mkdir my-agent && cd my-agent
matrix build            # no Matrixfile? one is scaffolded for you
# edit the Matrixfile
matrix build --increment minor
matrix publish --registry ghcr --tag stable

publish runs docker login with the registry's stored token when needed, pushes the versioned tag plus latest, and any extra --tags.

Build visually with Spawn

Matrix → Spawn walks the same configuration as numbered steps — Identity, Base, Tools (MCP server search), Skills, Model, Permissions, Prompt — with a live Matrixfile preview and a streamed build log. "Program" on any installed agent reopens Spawn seeded with its manifest, so iterating on an existing agent is edit-and-rebuild.

The composer state can also be driven from the CLI:

matrix spawn scaffold my-agent      # starter composer-state.json
matrix spawn search-mcp github      # find MCP servers
matrix spawn search-skills sql      # find skills
matrix spawn dockerfile state.json  # preview the generated Dockerfile
matrix spawn build state.json       # build it

What runs inside the container

At spawn time the platform injects:

The workspace is bind-mounted at /workspace:rw (or read-only if you set the filesystem permission to ro). Extra env vars from the Launch panel or --env flags are merged after the auto-injected ones and can override them.

Sandbox defaults: no network access unless PERMIT network true; nothing outside the workspace mount is visible. Access to real external systems goes through Exits, not open network.

OCI labels

Agent images carry their identity as labels, which is how any registry can host them without special support:

matrix info <name> prints the full manifest and labels for any installed agent.

Distributing more than one agent

Bundle agents into a pack — a single OCI artifact your whole team installs with one command (matrix pack import <ref>). For entire pre-configured companies, see Industry Packs.

Orchestration — Swarms, Networks & Loops

← Back to index

One agent is a tool. This page covers turning agents into teams (swarms), teams into a company (a network), and single runs into converging loops.

Swarms

A swarm is a set of installed agents wired into a team.

matrix swarm new dev-team
matrix swarm add-member dev-team coding-agent
matrix swarm add-member dev-team reviewer
matrix swarm entry dev-team coding-agent        # who receives the objective
matrix swarm line add dev-team coding-agent reviewer   # who may delegate to whom

In the app: Matrix → Swarms (list, launch) and Matrix → Hardline (wiring). Swarm members mount their own persistent memory, so members improve at their role across runs.

Hardline options

The Hardline is the communication contract, configurable per swarm and per network:

matrix swarm hardline dev-team     # interactive
matrix hardline dev-team           # same thing

Networks — a company of swarms

A network groups swarms into an isolated company with a shared workspace, shared knowledge base, its own Missions board, a budget pool, and optionally an accountable operator.

matrix network new acme-corp -d "Acme Corp" \
  --workspace ~/companies/acme \
  --objective "Build and maintain the Acme storefront" \
  --operator "Jay O'Keeffe" --operator-email jay@example.com

matrix network add-swarm acme-corp dev-team --role engineering --lead
matrix network add-swarm acme-corp research --role research
matrix network hardline acme-corp --topology star --max-rounds 6
matrix network line add acme-corp research dev-team

Then run the whole company:

matrix operator run --network acme-corp --objective "Ship the export feature"

What happens on a network run: the lead swarm receives the objective; open Missions tasks are pulled by agents (when pull-tasks is on); swarms exchange work along the drawn lines under the hardline rules; everything lands in the shared workspace; every message crosses the Wiretap; spend accrues against the network's budget pool.

Missions flow: tasks move backlog → in progress → done, each claimed task linking to its run. Agent-proposed features wait for your approval before becoming tasks.

Operator runs

matrix operator run (or Jack-In's assignment modal) is the single entry point for all targets:

matrix operator run --agent coding-agent  -o "…" -w ~/projects/app   # solo
matrix operator run --swarm dev-team      -o "…"                     # team
matrix operator run --network acme-corp   -o "…"                     # company

While a run is live you can steer it from the Jack-In composer — messages are delivered at the member's next step boundary — watch its Wiretap traffic, inspect containers, and stop it at any time.

Loop mode

A loop repeats the objective until a stop condition is met — for work that converges rather than completes in one pass:

matrix operator run --swarm dev-team -o "Make all tests pass" \
  --loop \
  --max-iterations 8 \      # hard ceiling
  --budget 15 \             # stop at $15 cumulative spend
  --stop-on-eval \          # stop early when an iteration passes its check
  --approve-each            # human approval before each extra iteration

Verifiers

A loop can attach an independent verifier that judges each iteration:

• Rubric verdicts — the verifier scores the iteration's staged output against a rubric and returns a structured verdict.
• Execution checks — the verifier runs checks against the staged output. Either commands you configure, or — in self-directed mode — checks the verifier proposes itself after inspecting the file tree, adapting to whatever the workers actually produced.
• N-of-M panels — multiple judges share the rubric and threshold; the panel must reach N approvals. Judges can sit on a different provider than the workers, so no model marks its own homework.

Delivery gate

Controls when a loop's result is promoted as the deliverable:

Patch — reusable one-off assignments

For recurring contractor-style work that doesn't need a swarm, save the brief once as a Patch assignment and fire it whenever: Operator → Patch, or matrix patch list|show|rm. Each assignment keeps its run history.

Governance & Security

← Back to index

Agents that act like employees are governed like employees: real identity, real budgets, verified output, controlled access to external systems, and a complete audit trail.

Sandboxing

Every agent runs in an isolated container:

• No network unless the image was built with PERMIT network true — and real external systems should go through Exits, not open network.
• Filesystem — only the chosen workspace is mounted (/workspace, rw or ro). Nothing else on the host is visible.
• Credentials — provider keys are injected at spawn, never baked into images. App-launched runs go further: the container only ever sees a per-run proxy key, never your real key (see token tracking).

Agent identity

Identity mode is set per install (surfaced in Sentinel → Bank):

• Local — agents are local identities; simplest, default.
• Entra — agents hold real Microsoft Entra ID user accounts: a digital mirror of a worker's access. Permissions, group membership, conditional access, and revocation work exactly as they do for people, and actions taken with that identity are attributable to it.

Just-in-time access elevations are tracked and listable: matrix bank elevations [agent].

Networks add a human anchor: the accountable operator (matrix network new --operator … --operator-email …) names the person who owns everything the company does — the audit boundary.

Budgets and spend

Spend is tracked from exact token counts (app-launched runs) and rolled up in the Bank ledger per run, agent, swarm, and network.

• Caps — global default run cap, per-agent caps, per-swarm caps, and network-wide pools. Caps are network-scoped.
• Enforcement — warn (log and continue) or hard (auto-stop the offending run on overrun), with a configurable warn threshold.

matrix budget mode hard
matrix budget warn-at 80
matrix budget set-pool acme-corp 200
matrix budget set-cap acme-corp coding-agent 50
matrix budget status acme-corp

Local-model routing savings are tracked too — Bank shows what routing to a local model saved versus cloud pricing.

Verified output

Loop runs can gate their deliverable behind independent verification — rubric verdicts, executing checks, N-of-M judge panels, cross-provider judges, and a delivery gate of none / verifier / human / both. Details: Orchestration → Loop mode.

Exits

An Exit is a controlled gateway from the sandbox to one real external system. Built-in exits: GitHub, GitLab, Jira, Slack, AWS, Kubernetes, Postgres, GitHub Actions.

Each exit declares:

• Access & tooling — the CLI baked into the image (e.g. gh for GitHub) and the exact allowed hosts. The container's network stays closed except for those hosts.
• Auth — how credentials are supplied, as env vars scoped to the minimum (e.g. contents:write, pull_requests:write). Where the system supports it, credentials are short-lived mints from the Keymaker (e.g. GitHub App installation tokens) — agents never hold long-lived secrets, and a leaked token dies on its own.
• Policy rules — per-verb decisions evaluated at the exit gate:

"rules": [
  { "verb": "pr.merge",        "policy": "approval" },
  { "verb": "push.default",    "policy": "deny" },
  { "verb": "repo.delete",     "policy": "deny" },
  { "verb": "release.publish", "policy": "approval" },
  { "verb": "*",               "policy": "allow" }
]

allow proceeds, approval pauses for a human (an EXIT-REQUEST you approve or reject), deny blocks outright. Every exit action and decision is emitted as a Wiretap event, so external side effects are as observable as internal messages.

Image trust

Pin agent images to a digest, verified at container start:

matrix images trust ghcr.io/me/coding-agent:latest   # pin at current digest
matrix images policy enforce                          # off | warn | enforce
matrix images list

Under enforce, an image whose digest no longer matches its pin will not run — supply-chain drift can't slip in via a mutable tag.

The audit trail

Three layers, none optional:

1. Uplink — every container run: agent, workspace, start/end, duration, exit status, token counts. Last 500 runs, from both app and CLI.
2. Wiretap — every inter-agent and swarm message, plus exit events, filterable by kind/network/swarm.
3. Bank ledger — every run's cost, attributable to agent, swarm, and network, with tool usage per run.

Key storage

• Desktop app: OS keychain encryption (safeStorage).
• CLI: ~/.matrix/credentials.json, mode 0600 plaintext.
• Registry tokens: ~/.matrix/registry-secrets.json, mode 0600.

If you use both surfaces, keep provider keys in the app.

Automation — Déjà Vu & CI/CD

← Back to index

Déjà Vu runs agents without you at the keyboard. Three trigger types, all persistent across restarts, managed in Sentinel → Déjà Vu or matrix deja-vu.

Trigger types

Each trigger specifies the agent, the workspace to mount, and optionally a network scope.

Managing triggers

In the app: the new-trigger form (segmented type switch, workspace picker, optional network select), per-trigger Run now, enable/disable toggle, and delete. Stat chips count cron/watch/webhook triggers, and a scope filter narrows by network.

From the CLI:

matrix deja-vu add            # interactive: agent, workspace, trigger type + value
matrix deja-vu list
matrix deja-vu toggle <id>
matrix deja-vu run <id>       # fire immediately
matrix deja-vu remove <id>

Definitions live in ~/.matrix/schedules.json.

Webhooks from CI/CD

Webhook triggers print their endpoint when created. POST to it from any pipeline on the same machine:

curl -X POST http://localhost:9119/hook/d9e7f4a
# → {"ok":true,"agentName":"coding-agent"}

Typical patterns:

• Post-merge review — CI calls the webhook after merge; a review agent runs against the fresh checkout.
• Nightly maintenance — cron trigger runs a dependency-audit agent over each repo at 2am.
• Docs on change — a watch trigger on src/ keeps generated docs current.

Scheduled runs are still governed

Triggered runs are ordinary runs: they appear in Uplink, their messages cross the Wiretap, and budget caps and enforcement apply. A runaway 2am loop hits its cap and stops like anything else.

Industry Packs

← Back to index

An industry pack is a whole pre-configured company: a role matrix that compiles into real agents, department swarms, a network, seed missions, and per-agent eval suites. Install one and you have a working company for your domain in minutes.

Available packs

Software Delivery · Finance & Accounting · Healthcare Admin · Legal Ops · Marketing Agency · MSP / IT Ops · E-commerce & Retail · Insurance Ops · Manufacturing & SCM · Real Estate · Recruitment & Staffing · Education

matrix industry list

In the app, packs appear under Matrix → Recruits → Enterprises.

How a pack is built

Each pack is a pack.json role matrix — department × role × seniority — expanded against a shared archetype library (hand-tuned role "process cores"). The compiler produces:

• a Matrixfile per agent (archetype core + the pack's industry-specific focus),
• swarm YAML per department,
• a company network wiring the departments together,
• seed tasks for the network's Missions board,
• an eval suite per agent (3–5 tasks: archetype defaults + role-specific).

matrix industry build finance-accounting     # compile → <pack>/dist

Installing

matrix industry install finance-accounting \
  --gate claude-haiku-4-5-20251001           # run the eval gate first
matrix industry install software-delivery --build   # also build the Docker images

Install saves the department swarms and company network into ~/.matrix, seeds the Missions board with the pack's starter tasks, and applies the pack's default budget pool and identity mode.

The quality gate

With --gate <model>, every generated agent must pass its own eval suite before the install is accepted. An agent that can't pass its evals doesn't ship — the install is refused with a per-agent, per-eval failure report.

Expectations are deterministic (substrings, regex, minimum length — no LLM judging), so the gate is cheap and reproducible; run it against a small model in CI.

After install

The company is a normal network. Give it work:

matrix operator run --network finance-accounting --objective "Close the June books"

Missions, budgets, Wiretap, identity, and verifiers all apply as usual — see Orchestration and Governance.

Writing your own pack

A pack folder is packs/<industry>/pack.json: choose an archetype per role, add an industry focus, list departments and seniorities, seed missions, and set budget/identity defaults. Compile with matrix industry build and check the generated Matrixfiles in <pack>/dist before installing.

Troubleshooting & FAQ

← Back to index

Container engine

"Docker not running" banner / engine unreachable

The app and CLI need a running container engine. Any of these work: Docker Desktop, Docker Engine, Podman, Colima, OrbStack. The engine socket is configurable — you are not tied to the default docker.sock path. Start your engine, then hit Retry on the banner (app) or re-run the command (CLI).

Containers can't reach my local model

Custom provider URLs pointing at localhost are rewritten to host.docker.internal automatically so containers can reach the host. If your engine doesn't support host.docker.internal (some Linux setups), add the host-gateway mapping in your engine config or use the machine's LAN address in the provider URL.

Runs

Token counts missing for CLI runs

Expected. The token-tracking proxy runs inside the desktop app's process; app-launched runs get exact counts, matrix run from the CLI injects keys directly and records timing/status only. Launch from the app when you need per-run token numbers. Details: CLI Reference → Token tracking.

A run won't stop

matrix stop <id|name>, or Switchboard → Stop (or Stop all). Switchboard shows the live container list if you're unsure what's running.

The agent asks a question and hangs

Runs are interactive. Type into the run console (app) or matrix attach <id|name> (CLI) and press Enter to send input.

An image won't run under image trust

If matrix images policy is enforce and the image digest no longer matches its pin, the run is refused. Re-pin deliberately with matrix images trust <image> after checking why the digest changed.

Budgets

My run stopped mid-flight

Check matrix budget status [network] — under hard enforcement, a run that exceeds its cap (agent, swarm, or pool) is auto-stopped. Raise the cap or switch to warn.

Where things live

Everything is in ~/.matrix/ — the full file table is in the CLI Reference. Uninstalling the app does not delete this directory, so your agents, history, and schedules survive reinstalls.

FAQ

Do you see my API keys or data? No. Keys stay on your machine (app: OS keychain; CLI: 0600 file) and runs are local containers. The token proxy also keeps real keys out of the containers themselves.

Can the app and CLI be used together? Yes — same state directory, fully interchangeable. Prefer the app for key storage.

Can agents access the internet? Only if built with PERMIT network true, and access to real systems (GitHub, Jira, AWS…) should go through Exits, which pin allowed hosts and enforce per-verb policy.

What models can I use? Anthropic, OpenAI, Google, or any OpenAI-compatible endpoint including local models (Ollama, LM Studio, llama.cpp). Swap per run with --model. matrix architect tells you what your machine can run locally.

How do I move my setup to a new machine? Copy ~/.matrix/ and re-pull images (matrix update). Registries, swarms, networks, schedules, and history come with the directory.

Is it free? Free for personal use and teams up to 5. Larger teams and enterprise support: redpill@kodacity.ai.