Armada

Reduce context switching across projects. Keep agent work in queryable memory.
v0.4.0 alpha -- APIs and schemas may change

Why Armada | How It Works | Quick Start | Pipelines | Use Cases | Architecture | API | MCP

---

Why Armada

Armada is for people working across multiple repositories who are tired of paying the context-switching tax every time they come back to a project.

The first problem is operational: switching between projects means rebuilding context over and over. What was in flight, what already landed, what failed, what the agent was about to do next. That overhead adds up fast.

The second problem is memory. Most agent sessions disappear into terminal history and branch diffs. A week later, neither you nor the next agent has a clean way to ask "what happened here?" without manually piecing it back together.

Armada is built around those two problems:

1. Reduce context switching across projects. Armada keeps the state of work outside your head. You can dispatch, leave, come back later, and see where things stand without reconstructing everything from scratch.

2. Provide extended, queryable memory for both users and agents. Missions, logs, diffs, status changes, and related work are preserved behind a searchable interface. You no longer have to remember what you were working on; you can ask. Agents can do the same.

Armada gives models a place to maintain working context on a vessel over time. Agents can update vessel context with notes, hints, and project-specific guidance so the next dispatch does not have to rediscover the same facts from scratch. That reduces context load time for both humans and models.

Everything else in Armada exists to support that: isolated worktrees, parallel dispatch, pipelines, retries, dashboards, API access, and MCP tools.

What You Get

• Less project-switch overhead. Leave one repo, work somewhere else, then come back to a current view of what happened.
• A queryable memory layer. Logs, diffs, status history, and agent output stay available through the dashboard, API, and MCP instead of vanishing into scrollback.
• Persistent vessel context. Models can maintain repository-specific context, hints, and working notes on each vessel to speed up future dispatches.
• Parallel execution across repos. Dispatch work to multiple agents across multiple repositories at once.
• Quality gates that run automatically. Every piece of work can flow through a pipeline: plan it, implement it, test it, review it. No manual intervention between steps.
• Git isolation by default. Every agent works in its own worktree on its own branch. Agents can't step on each other. Your main branch stays clean until you merge.
• Configurable and extensible workflows. Prompt templates, personas, and pipelines are user-controlled, so you can adapt the system to your project instead of fitting your project to the built-ins.
• Works with the agents you already have. Claude Code, Codex, Gemini, Cursor -- pluggable runtime system.

Who It's For

• Solo developers working across multiple repos.
• Tech leads who want a record of what agents changed.
• Teams that need shared visibility into agent-driven work.
• Anyone who wants more structure than a single-agent terminal loop.

---

How It Works

+-----------------------------------------------------------+ | You: "Build a FastAPI backend with user auth and tests" | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | Admiral | | Coordinates work, resolves pipeline, assigns captains, | | provisions worktrees, and tracks mission state | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | Architect | | Reads the codebase, breaks work into missions, and | | identifies file boundaries | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | Worker | | Implements the mission in an isolated git worktree | | and produces a diff | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | TestEngineer | | Reviews the worker diff and adds or updates tests | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | Judge | | Reviews correctness, completeness, scope, and style | | Produces PASS or FAIL | +-----------------------------------------------------------+

1. You describe the goal. This can be a short prompt or a longer spec.
2. The Architect plans. It reads the codebase, breaks the work into missions, and identifies likely file boundaries.
3. Workers implement. Each worker runs in its own git worktree on its own branch.
4. TestEngineers add tests. They get the worker diff as input.
5. Judges review. They check the result against the original task and return a pass/fail verdict.

Each step is a persona with its own prompt template. A sequence of personas is a pipeline. The built-ins are just defaults; pipelines are user-configurable and can be extended with whatever personas your project needs:

Pipeline	Stages	When to use
WorkerOnly	Implement	Quick fixes, one-liners
Reviewed	Implement -> Review	Normal development
Tested	Implement -> Test -> Review	When you need coverage
FullPipeline	Plan -> Implement -> Test -> Review	Big features, unfamiliar codebases

You can set a default pipeline per repository and override it on a single dispatch when needed. If the built-in roles are not enough, define your own personas and compose them into custom pipelines for security review, documentation, migration planning, release checks, architecture review, or any other project-specific step.

Parallel Tasks

Semicolons or numbered lists split a prompt into separate missions. Armada can assign those to different agents:

armada go "Add rate limiting; Add request logging; Add input validation"

armada go "1. Add auth middleware 2. Add login endpoint 3. Add token validation"

Auto-Recovery

If a captain crashes, the Admiral can repair the worktree and relaunch the agent up to MaxRecoveryAttempts times (default: 3).

Quick Start

Prerequisites

• .NET 8.0+ SDK
• At least one AI agent runtime on your PATH:
  • Claude Code (claude)
  • Codex (codex)
  • Gemini CLI (gemini)
  • Cursor (cursor-agent)

Install

git clone https://github.com/jchristn/armada.git
cd armada
./install.sh    # or install.bat on Windows

Helper scripts are in the project root: install.bat/.sh, remove.bat/.sh, reinstall.bat/.sh, and update.bat/.sh.

Your First Dispatch

cd your-project
armada go "Add input validation to the signup form"
armada watch   # monitor progress in real time

Armada detects the runtime, infers the current repository, provisions a worktree, and dispatches the task.

Default Credentials

On first boot, Armada seeds a default tenant, user, and credential:

Item	Value
Email	admin@armada
Password	password
Bearer Token	default

Dashboard at http://localhost:7890/dashboard. API access with Authorization: Bearer default.

Security: Armada runs agents with auto-approve flags by default (Claude Code: --dangerously-skip-permissions, Codex: --full-auto, Gemini: --approval-mode yolo). Agents can read, write, and execute in their worktrees without confirmation. Review the configuration section before running in sensitive environments.

Important: Change the default password in production environments.

For a deeper walkthrough, see the Getting Started Guide.

Pipelines

Pipelines are the workflow layer in Armada. They let you run work through explicit stages instead of treating every task as a single agent session.

Built-in Personas

Persona	Role	What it does
Architect	Plan	Reads the codebase, decomposes a high-level goal into concrete missions with file lists and dependency ordering
Worker	Implement	Writes code. The default -- this is what you get without pipelines.
TestEngineer	Test	Receives the Worker's diff, identifies gaps in coverage, writes tests
Judge	Review	Examines the diff against the original mission description. Checks completeness, correctness, scope violations, style. Produces a verdict.

Pipeline Resolution

When you dispatch, Armada picks the pipeline in this order:

Priority	Source	How to set
1 (highest)	Dispatch parameter	--pipeline FullPipeline on the CLI or pipeline in the API
2	Vessel default	Set on the repository in the dashboard or via API
3	Fleet default	Set on the fleet -- applies to all repos in the fleet unless overridden
4 (lowest)	System fallback	WorkerOnly

Custom Personas and Pipelines

The four built-in personas are starting points. You can create your own:

# Create a security auditor persona with custom instructions
armada_update_prompt_template name=persona.security_auditor content="Review for OWASP vulnerabilities..."
armada_create_persona name=SecurityAuditor promptTemplateName=persona.security_auditor

# Build a pipeline that includes security review
armada_create_pipeline name=SecureRelease stages='[{"personaName":"Worker"},{"personaName":"SecurityAuditor"},{"personaName":"Judge"}]'

Every prompt Armada sends is backed by an editable template. You can change agent behavior without modifying code. The dashboard includes a template editor with a parameter reference panel.

Pipelines are not limited to planning, implementation, testing, and review. If a project needs a SecurityAuditor, PerformanceAnalyst, MigrationPlanner, DocsWriter, ReleaseManager, or some internal role with custom instructions and handoff rules, Armada can support that by adding the persona and inserting it into the pipeline.

For the full pipeline reference, see docs/PIPELINES.md.

Use Cases

Solo Developer Multiplier

If a feature depends on a few independent refactors, you can dispatch them together instead of working through them serially:

armada go "1. Extract UserRepository from UserService 2. Add ILogger to all controllers 3. Migrate config to Options pattern"

That gives you three parallel branches to review instead of one long queue.

Ship with Confidence

Set Tested as the default pipeline if you want implementation, test generation, and review on every dispatch.

Code Review Prep

Batch mechanical cleanup before opening a review:

armada voyage create "Pre-review cleanup" --vessel my-api \
  --mission "Add XML documentation to all public methods in Controllers/" \
  --mission "Replace magic strings with constants in Services/" \
  --mission "Add input validation to all POST endpoints"

Multi-Repo Coordination

Dispatch related changes across multiple repositories:

armada go "Update the shared DTOs to include CreatedAt field" --vessel shared-models
armada go "Add CreatedAt to the API response serialization" --vessel backend-api
armada go "Display CreatedAt in the user profile component" --vessel frontend-app

Prototyping and Exploration

Try a few approaches in parallel:

armada voyage create "Auth approach comparison" --vessel my-api \
  --mission "Implement JWT-based authentication with refresh tokens" \
  --mission "Implement session-based authentication with Redis store" \
  --mission "Implement OAuth2 with Google and GitHub providers"

Review the branches, keep one, and drop the others.

Bug Triage

Spread investigation and fixes across multiple reported issues:

armada go "Fix: login fails when email contains a plus sign" --vessel auth-service
armada go "Fix: pagination returns duplicate results on page 2" --vessel search-api
armada go "Fix: file upload silently fails for files over 10MB" --vessel upload-service

Let AI Manage AI

If you connect Claude Code to Armada's MCP server, Claude can act as the orchestrator: decompose work into missions, dispatch them, and monitor progress.

> "Refactor the authentication system. Decompose it into parallel missions
   and dispatch them via Armada. Monitor progress and redispatch failures."

See Claude Code as Orchestrator for setup.

Screenshots

Click to expand

Architecture

Armada is a C#/.NET solution with five main projects:

Project	Description
Armada.Core	Domain models (including tenants, users, credentials), database interfaces, service interfaces, settings
Armada.Runtimes	Agent runtime adapters (Claude Code, Codex, Gemini, Cursor, extensible via IAgentRuntime)
Armada.Server	Admiral process: REST API (SwiftStack), MCP server (Voltaic), WebSocket hub, embedded dashboard
Armada.Dashboard	Standalone React dashboard for Docker/production deployments
Armada.Helm	CLI (Spectre.Console), thin HTTP client to Admiral

Key Concepts

Term	Plain Language	Description
Admiral	Coordinator	The server process that manages everything. Auto-starts when needed.
Captain	Agent/worker	An AI agent instance (Claude Code, Codex, etc.). Auto-created on demand.
Fleet	Group of repos	Collection of repositories. A default fleet is auto-created.
Vessel	Repository	A git repository registered with Armada. Auto-registered from your current directory.
Mission	Task	An atomic work unit assigned to a captain.
Voyage	Batch	A group of related missions dispatched together.
Dock	Worktree	A git worktree provisioned for a captain's isolated work.
Signal	Message	Communication between the Admiral and captains.
Persona	Agent role	A named agent role (Worker, Architect, Judge, TestEngineer) that determines what a captain does during a mission. Users can create custom personas with custom prompt templates.
Pipeline	Workflow	An ordered sequence of persona stages (e.g. Architect -> Worker -> TestEngineer -> Judge). Configured at fleet/vessel level with per-dispatch override.
Prompt Template	Instructions	A user-editable template controlling the instructions given to agents. Every prompt in the system is template-driven with {Placeholder} parameters.

For details on mission scheduling and assignment, see docs/SCHEDULING.md.

Data Model

+-------------------------------------------------------------+ | Admiral | | (coordinator process) | +--------+--------------+--------------+--------------+---------+ | | | | v v v v +---------+ +----------+ +----------+ +----------+ | Fleet | | Captain | | Voyage | | Signal | | (flt_) | | (cpt_) | | (vyg_) | | (sig_) | | | | | | | | | | group | | AI agent | | batch of | | message | | of repos| | worker | | missions | | between | +----+----+ +----+-----+ +----+-----+ | admiral | | | | | & agents | v | v +----------+ +----------+ | +----------+ | Vessel |<------+-------| Mission | | (vsl_) | | | (msn_) | | | | | | | git repo | +------>| one task | +----+-----+ assigns | for one | | captain | agent | v +----------+ +----------+ | Dock | | (dck_) | | | | git | | worktree | +----------+ Relationships: Fleet 1--* Vessel A fleet contains many vessels (repos) Vessel 1--* Dock A vessel has many docks (worktrees) Voyage 1--* Mission A voyage groups many missions Mission *--1 Vessel Each mission targets one vessel Mission *--1 Captain Each mission is assigned to one captain Captain 1--1 Dock A captain works in one dock at a time

Data Flow

User Command (CLI / API / MCP) | v Admiral receives command | +--> Creates/updates Mission in database +--> Resolves target Vessel (repository) +--> Allocates Captain (find idle or spawn new) +--> Provisions worktree (git worktree add) +--> Starts agent process with mission context +--> Monitors via stdout/stderr + heartbeat | Captain works autonomously | +--> Reports progress via signals +--> Admiral updates Mission status +--> On completion: push branch, create PR (optional) +--> Captain returns to idle pool

Technology Stack

Component	Technology	Notes
Language	C# / .NET 8+	Cross-platform
Database	SQLite, PostgreSQL, SQL Server, MySQL	SQLite default; zero-install, embedded
REST API	SwiftStack	OpenAPI built-in
MCP/JSON-RPC	Voltaic	Standards-compliant MCP server
CLI	Spectre.Console	Rich terminal UI
Logging	SyslogLogging	Structured logging
ID Generation	PrettyId	Prefixed IDs (flt_, vsl_, cpt_, msn_, etc.)

CLI Reference

Common Commands

armada go <prompt>           Quick dispatch (infers repo from current directory)
armada status                Dashboard (scoped to current repo)
armada status --all          Global view across all repos
armada watch                 Live dashboard with notifications
armada log <captain>         Tail a specific agent's output
armada log <captain> -f      Follow mode (like tail -f)
armada doctor                System health check

Missions and Voyages

armada mission list|create|show|cancel|retry
armada voyage list|create|show|cancel|retry

Entity Management

All commands accept names or IDs:

armada vessel list|add|remove
armada captain list|add|stop|stop-all
armada fleet list|add|remove

Infrastructure

armada server start|status|stop
armada config show|set|init
armada mcp install|remove|stdio

Examples

# Dispatch a single task in your current repo
armada go "Fix the null reference in UserService.cs"

# Dispatch three tasks in parallel
armada go "Add rate limiting; Add request logging; Add input validation"

# Work with a specific repo
armada go "Fix the login bug" --vessel my-api

# Register additional repos
armada vessel add my-api https://github.com/you/my-api
armada vessel add my-frontend https://github.com/you/my-frontend

# Add more agents (supports claude, codex, gemini, cursor)
armada captain add claude-2 --runtime claude
armada captain add codex-1 --runtime codex
armada captain add gemini-1 --runtime gemini

# Emergency stop all agents
armada captain stop-all

# Retry a failed mission
armada mission retry msn_abc123

# Retry all failed missions in a voyage
armada voyage retry "API Hardening"

Configuration

Settings live in ~/.armada/settings.json and are created on first use.

armada config show              # View current settings
armada config set MaxCaptains 8 # Change a setting
armada config init              # Interactive setup (optional)

Setting	Default	Description
AdmiralPort	7890	REST API port
MaxCaptains	0 (auto, defaults to 5)	Maximum total captains
StallThresholdMinutes	10	Minutes before a captain is considered stalled
MaxRecoveryAttempts	3	Auto-recovery attempts before giving up
AutoPush	true	Push branches to remote on mission completion
AutoCreatePullRequests	false	Create PRs on mission completion
AutoMergePullRequests	false	Auto-merge PRs after creation
LandingMode	null	Landing policy: LocalMerge, PullRequest, MergeQueue, or None
BranchCleanupPolicy	LocalOnly	Branch cleanup after landing: LocalOnly, LocalAndRemote, or None
RequireAuthForShutdown	false	Require authentication for POST /api/v1/server/stop
TerminalBell	true	Ring terminal bell during armada watch
DefaultRuntime	null (auto-detect)	Default agent runtime

Authentication

As of v0.3.0, Armada supports multi-tenant authentication with three methods:

Method	Header	Description
Bearer Token (recommended)	Authorization: Bearer <token>	64-character tokens linked to a tenant and user. Default token: default
Session Token	X-Token: <token>	AES-256-CBC encrypted, 24-hour lifetime. Returned by POST /api/v1/authenticate
API Key (deprecated)	X-Api-Key: <key>	Legacy. Maps to a synthetic admin identity. Migrate to bearer tokens

The default installation works with Authorization: Bearer default.

All operational data is tenant-scoped. The authorization model:

• IsAdmin = true: global system admin with access to every tenant and object.
• IsAdmin = false, IsTenantAdmin = true: tenant admin with management access inside that tenant, including users and credentials.
• IsAdmin = false, IsTenantAdmin = false: regular user with tenant-scoped visibility plus self-service on their own account and credentials.

For full details, see docs/REST_API.md.

REST API

The Admiral exposes a REST API on port 7890. Endpoints are under /api/v1/ and require authentication unless noted otherwise. Error responses use a standard format with Error, Description, Message, and Data fields; see REST_API.md for details.

API="http://localhost:7890/api/v1"
AUTH="Authorization: Bearer default"

curl -H "$AUTH" $API/status              # System status
curl -H "$AUTH" $API/fleets              # List fleets
curl -H "$AUTH" $API/vessels             # List vessels
curl -H "$AUTH" $API/missions            # List missions
curl -H "$AUTH" $API/captains            # List captains
curl $API/status/health                  # Health check (no auth required)

Full CRUD endpoints are available for fleets, vessels, missions, voyages, captains, signals, events, tenants, users, and credentials.

Start the Admiral as a standalone server:

armada server start

MCP Integration

Armada also exposes an MCP (Model Context Protocol) server so Claude Code and other MCP-compatible clients can call Armada tools directly.

armada mcp install    # Configure Claude Code, Codex, Gemini, and Cursor for Armada MCP
armada mcp remove     # Remove those Armada MCP entries again

If you are working from source, repo-root helpers are also available: install-mcp.bat/.sh and remove-mcp.bat/.sh.

Once installed, your MCP client can call tools like armada_status, armada_dispatch, armada_enumerate, armada_voyage_status, and armada_cancel_voyage. There are also tool groups for persona, pipeline, and prompt-template management.

AI-Powered Orchestration

If you connect Claude Code, Codex, or another MCP-capable client to Armada, that client can act as the orchestrator. Armada handles the worktrees, state, and process management underneath.

Claude Code (orchestrator) --MCP--> Armada Server --spawns--> Captain agents (workers)

For detailed setup and examples, see:

• Claude Code as Orchestrator
• Codex as Orchestrator

Running Locally (without Docker)

Prerequisites

• .NET 8.0+ SDK
• At least one AI agent runtime on your PATH (Claude Code, Codex, Gemini, or Cursor)

Build and Run

git clone https://github.com/jchristn/armada.git
cd armada

# Build the solution
dotnet build src/Armada.sln

# Run the server directly
dotnet run --project src/Armada.Server

The server starts on the following ports:

Port	Protocol	Description
7890	HTTP	REST API + embedded dashboard
7891	JSON-RPC	MCP server
7892	WebSocket	Real-time event hub

Open http://localhost:7890/dashboard in your browser. Configuration is stored in armada.json in the working directory. On first run, Armada creates the SQLite database, applies migrations, and seeds default data.

Install the CLI (optional)

dotnet pack src/Armada.Helm -o ./nupkg
dotnet tool install --global --add-source ./nupkg Armada.Helm

# Then use the CLI from any directory
armada doctor
armada go "your task here"

Run Tests

dotnet run --project test/Armada.Test.Unit

Running Locally (with Docker)

Docker Compose can run the server and the optional React dashboard in containers, so the host does not need the .NET SDK.

Prerequisites

• Docker with Docker Compose v2

Start

cd docker
docker compose up -d

Services

Service	Port	URL	Description
armada-server	7890	http://localhost:7890/dashboard	REST API, MCP, WebSocket, embedded dashboard
armada-dashboard	3000	http://localhost:3000	Standalone React dashboard

Both dashboards connect to the same server. The embedded dashboard at port 7890 is always available. The React dashboard at port 3000 is an optional separate frontend.

Data Persistence

Docker volumes are mapped to docker/armada/:

docker/
+-- armada/
|   +-- db/          # SQLite database (persistent across restarts)
|   +-- logs/        # Server logs
+-- server/
|   +-- armada.json  # Server configuration
+-- compose.yaml

To change settings, edit docker/server/armada.json and restart:

docker compose restart armada-server

Factory Reset

To delete all data and start fresh (preserves configuration):

cd docker/factory

# Linux/macOS
./reset.sh

# Windows
reset.bat

Stop

cd docker
docker compose down

Build Images Locally

To build the Docker images from source instead of pulling from Docker Hub:

# Build server image
docker build -f src/Armada.Server/Dockerfile -t armada-server:local .

# Build dashboard image
docker build -f src/Armada.Dashboard/Dockerfile -t armada-dashboard:local .

Build scripts for multi-platform images are also provided: build-server.bat/.sh and build-dashboard.bat/.sh.

Upgrading / Migration

When upgrading between major versions, your settings.json may need to be updated.

v0.1.0 to v0.2.0

Breaking change: The settings.json format changed. Armada v0.2.0 will fail to start with a v0.1.0 settings.json.

The databasePath string property was replaced with a database object supporting multiple backends (SQLite, PostgreSQL, SQL Server, MySQL).

Before (v0.1.0)

{
  "databasePath": "armada.db",
  "admiralPort": 7890,
  "maxCaptains": 5
}

After (v0.2.0)

{
  "database": {
    "type": "Sqlite",
    "filename": "armada.db"
  },
  "admiralPort": 7890,
  "maxCaptains": 5
}

Minimal change for SQLite users

Replace:

"databasePath": "path/to/armada.db"

With:

"database": {
  "type": "Sqlite",
  "filename": "path/to/armada.db"
}

No other changes are required -- all other settings remain the same.

Switching to PostgreSQL

"database": {
  "type": "Postgresql",
  "hostname": "localhost",
  "port": 5432,
  "username": "armada",
  "password": "your-password",
  "databaseName": "armada",
  "schema": "public",
  "minPoolSize": 1,
  "maxPoolSize": 25,
  "connectionLifetimeSeconds": 300,
  "connectionIdleTimeoutSeconds": 60
}

Switching to SQL Server

"database": {
  "type": "SqlServer",
  "hostname": "localhost",
  "port": 1433,
  "username": "armada",
  "password": "your-password",
  "databaseName": "armada",
  "minPoolSize": 1,
  "maxPoolSize": 25,
  "connectionLifetimeSeconds": 300,
  "connectionIdleTimeoutSeconds": 60
}

Switching to MySQL

"database": {
  "type": "Mysql",
  "hostname": "localhost",
  "port": 3306,
  "username": "armada",
  "password": "your-password",
  "databaseName": "armada",
  "minPoolSize": 1,
  "maxPoolSize": 25,
  "connectionLifetimeSeconds": 300,
  "connectionIdleTimeoutSeconds": 60
}

Additional notes

• Port auto-detection: Setting port to 0 (or omitting it) auto-detects the default port for each database type (PostgreSQL: 5432, SQL Server: 1433, MySQL: 3306).
• Connection pooling: All non-SQLite backends support connection pooling via minPoolSize (0-100), maxPoolSize (1-200), connectionLifetimeSeconds (minimum 30), and connectionIdleTimeoutSeconds (minimum 10).
• Encryption: Set requireEncryption to true to require encrypted connections for PostgreSQL, SQL Server, or MySQL.
• Backup/restore: The armada_backup and armada_restore MCP tools are only available when using SQLite. If you switch to PostgreSQL, SQL Server, or MySQL, use your database's native backup tools instead.

Automated migration script

For existing v0.1.0 deployments, run the migration script to automatically convert your settings.json:

Windows:

migrations\migrate_v0.1.0_to_v0.2.0.bat
# or with a custom path:
migrations\migrate_v0.1.0_to_v0.2.0.bat C:\path\to\settings.json

Linux/macOS:

./migrations/migrate_v0.1.0_to_v0.2.0.sh
# or with a custom path:
./migrations/migrate_v0.1.0_to_v0.2.0.sh /path/to/settings.json

The script backs up your original file to settings.json.v0.1.0.bak before making changes.

Requires: jq (Linux/macOS) -- install via apt install jq, brew install jq, etc.

v0.2.0 to v0.3.0

v0.3.0 introduces multi-tenant support. The database schema is automatically migrated on first startup. Key changes:

• New tables: TenantMetadata, UserMaster, Credential are created automatically
• Default data seeded: A default tenant (default), user (admin@armada / password), and credential (bearer token default) are created if no tenants exist
• All operational tables gain TenantId: Existing rows are assigned to the default tenant during migration
• All operational tables gain UserId: Existing rows are assigned to the earliest user in their tenant during migration
• Ownership integrity: Operational TenantId and UserId columns are indexed and protected by database foreign keys across all supported backends
• Protected auth resources: The default tenant, its default user/credential, and the synthetic system records are seeded as protected and cannot be deleted directly
• Role model: IsAdmin now means global system admin. IsTenantAdmin means tenant-scoped admin. Regular users are limited to their own tenant, own account, and own credentials
• Password management: User create/update APIs accept plaintext Password; the server hashes it before persistence. Leaving Password blank on update preserves the existing password. The dashboard exposes this through the Users edit modal for both admin-managed and self-service password changes
• Protected resources: IsProtected is server-controlled on tenants, users, and credentials. Protected objects cannot be deleted directly, and immutable identifiers/timestamps/ownership fields are preserved on update
• Tenant-created seed admin: Creating a tenant also creates admin@armada with password password plus a default credential inside that tenant; that seeded user is tenant admin only (IsAdmin = false, IsTenantAdmin = true) and those child resources are protected from direct delete
• Authentication required: All REST API endpoints now require authentication. Use Authorization: Bearer default for backward-compatible access
• X-Api-Key deprecated: The X-Api-Key header still works but is deprecated. If configured, it maps to a synthetic admin identity. Migrate to bearer tokens
• New settings: AllowSelfRegistration (default: true), RequireAuthForShutdown (default: false), SessionTokenEncryptionKey (auto-generated)

No manual changes to settings.json are required. Existing ApiKey settings continue to work.

v0.3.0 to v0.4.0

v0.4.0 adds personas, pipelines, and prompt templates. The database schema is automatically migrated on first startup (migrations 19-23). Key changes:

• New tables: prompt_templates, personas, pipelines, pipeline_stages
• New columns: captains.allowed_personas, captains.preferred_persona, missions.persona, missions.depends_on_mission_id, fleets.default_pipeline_id, vessels.default_pipeline_id
• Built-in personas (Worker, Architect, Judge, TestEngineer) and pipelines (WorkerOnly, Reviewed, Tested, FullPipeline) are seeded automatically
• 18 built-in prompt templates are seeded automatically
• Standalone migration scripts available in migrations/ for manual execution

Issues and Discussions

• Bug reports and feature requests: Open an issue on GitHub. Please include your OS, .NET version, agent runtime, and steps to reproduce.
• Questions and discussions: Start a discussion on GitHub for general questions, ideas, or feedback.

When filing an issue, include:

1. What you expected to happen
2. What actually happened
3. Output of armada doctor
4. Relevant log output (armada log <captain>)

License

Armada is released under the MIT License. See the LICENSE.md file for details.