{"id":44390050,"url":"https://github.com/stepandel/agent-army","last_synced_at":"2026-02-17T02:17:30.190Z","repository":{"id":337708771,"uuid":"1152363985","full_name":"stepandel/agent-army","owner":"stepandel","description":"Army of agents ready to work for your tech startup","archived":false,"fork":false,"pushed_at":"2026-02-12T04:07:18.000Z","size":767,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T10:56:55.157Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://agent-army.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stepandel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.mdx","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T19:06:57.000Z","updated_at":"2026-02-12T03:55:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stepandel/agent-army","commit_stats":null,"previous_names":["stepandel/agent-army"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/stepandel/agent-army","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepandel%2Fagent-army","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepandel%2Fagent-army/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepandel%2Fagent-army/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepandel%2Fagent-army/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stepandel","download_url":"https://codeload.github.com/stepandel/agent-army/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepandel%2Fagent-army/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29392762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T00:53:09.511Z","status":"online","status_checked_at":"2026-02-13T02:00:10.076Z","response_time":78,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-12T02:20:09.763Z","updated_at":"2026-02-13T03:01:52.653Z","avatar_url":"https://github.com/stepandel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Army 🪖\n\n[![npm](https://img.shields.io/npm/v/agent-army)](https://www.npmjs.com/package/agent-army)\n[![license](https://img.shields.io/npm/l/agent-army)](./LICENSE)\n\nDeploy a fleet of specialized [OpenClaw](https://openclaw.bot/) AI agents on **AWS** or **Hetzner Cloud** — managed entirely from your terminal.\n\n## What Is This?\n\nAgent Army provisions a team of autonomous AI agents that handle software engineering tasks — product management \u0026 research, development, and QA — with persistent memory and role-specific behavior. Agents communicate over a secure Tailscale mesh VPN with no public port exposure.\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                      AWS VPC / Hetzner Cloud                        │\n│                                                                     │\n│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐             │\n│  │  Juno (PM)   │   │ Titus (Eng)  │   │ Scout (QA)   │             │\n│  │              │   │              │   │              │             │\n│  │  • OpenClaw  │   │  • OpenClaw  │   │  • OpenClaw  │             │\n│  │  • Docker    │   │  • Docker    │   │  • Docker    │             │\n│  │  • Tailscale │   │  • Tailscale │   │  • Tailscale │             │\n│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘             │\n│         └──────────────────┼──────────────────┘                     │\n└────────────────────────────┼────────────────────────────────────────┘\n                             │\n                ┌────────────▼────────────┐\n                │   Tailscale Mesh VPN    │\n                │   (Encrypted P2P)       │\n                └────────────┬────────────┘\n                             │\n                ┌────────────▼────────────┐\n                │     Your Machine        │\n                └─────────────────────────┘\n```\n\n## Quick Start\n\nEverything is done through the CLI.\n\n### 1. Install\n\n```bash\nnpm install -g agent-army\n```\n\n### 2. Run the Setup Wizard\n\n```bash\nagent-army init\n```\n\nThe wizard walks you through:\n- **Prerequisites check** — verifies Pulumi, Node.js, cloud provider CLI, and Tailscale\n- **Cloud provider** — AWS or Hetzner Cloud\n- **Region \u0026 instance type** — with cost estimates shown inline\n- **Secrets** — Anthropic API key, Tailscale auth key (with instructions for each)\n- **Agent selection** — pick from presets, define custom agents, or mix both\n- **Optional integrations** — Slack, Linear, GitHub per agent\n- **Review \u0026 confirm** — see full config and estimated monthly cost\n\nThis generates an `agent-army.json` manifest and sets all Pulumi config values automatically.\n\n### 3. Deploy\n\n```bash\nagent-army deploy\n```\n\n### 4. Validate\n\nWait 3-5 minutes for cloud-init to complete, then:\n\n```bash\nagent-army validate\n```\n\n### 5. Access Your Agents\n\n```bash\nagent-army ssh juno    # SSH to PM agent\nagent-army ssh titus     # SSH to Engineer agent\nagent-army ssh scout     # SSH to QA agent\n```\n\n## CLI Reference\n\nThe CLI is the primary interface for every operation. Run `agent-army --help` for the full list.\n\n| Command | Description |\n|---------|-------------|\n| `agent-army init` | Interactive setup wizard |\n| `agent-army deploy` | Deploy agents (`pulumi up` under the hood) |\n| `agent-army deploy -y` | Deploy without confirmation prompt |\n| `agent-army status` | Show agent statuses and outputs |\n| `agent-army status --json` | Status in JSON format |\n| `agent-army ssh \u003cagent\u003e` | SSH to an agent by name, role, or alias |\n| `agent-army ssh \u003cagent\u003e '\u003ccmd\u003e'` | Run a command on an agent remotely |\n| `agent-army validate` | Health check all agents via Tailscale |\n| `agent-army destroy` | Tear down all resources (with confirmation) |\n| `agent-army destroy -y` | Tear down without confirmation |\n| `agent-army list` | List saved configurations |\n\nAgent resolution is flexible — all of these target the same agent:\n\n```bash\nagent-army ssh juno      # by alias\nagent-army ssh pm          # by role\nagent-army ssh agent-pm    # by resource name\n```\n\n## Preset Agents\n\nAgent Army ships with three battle-tested agent presets:\n\n| Alias | Role | What It Does |\n|-------|------|-------------|\n| **Juno** | PM | Breaks down tickets, researches requirements, plans \u0026 sequences work, tracks progress, unblocks teams |\n| **Titus** | Engineer | Picks up tickets, writes code via Claude Code, builds/tests, creates PRs, responds to reviews |\n| **Scout** | Tester | Reviews PRs, tests happy/sad/edge cases, files bugs, verifies fixes |\n\nEach agent is defined by workspace files in `presets/`:\n\n```\npresets/\n├── base/           # Shared across all agents (AGENTS.md, BOOTSTRAP.md, USER.md)\n├── pm/             # Juno: SOUL.md, IDENTITY.md, HEARTBEAT.md, TOOLS.md\n├── eng/            # Titus: SOUL.md, IDENTITY.md, HEARTBEAT.md, TOOLS.md\n├── tester/         # Scout: SOUL.md, IDENTITY.md, HEARTBEAT.md, TOOLS.md\n└── skills/         # Reusable skills (ticket prep, PR testing, review workflows)\n```\n\nYou can also define fully custom agents during `agent-army init`.\n\n### Customizing Agent Behavior\n\n| File | Purpose |\n|------|---------|\n| `SOUL.md` | Personality, role, approach, communication style |\n| `IDENTITY.md` | Name, role, emoji |\n| `HEARTBEAT.md` | Periodic tasks and state machine logic |\n| `TOOLS.md` | Tool reference (Linear, Slack, GitHub, local env) |\n\nTemplate variables are supported in preset files:\n\n| Variable | Description |\n|----------|-------------|\n| `{{OWNER_NAME}}` | Agent owner name |\n| `{{TIMEZONE}}` | Owner timezone |\n| `{{WORKING_HOURS}}` | Working hours for scheduling |\n| `{{USER_NOTES}}` | Custom notes for the agent |\n| `{{LINEAR_TEAM}}` | Default Linear team ID |\n| `{{GITHUB_REPO}}` | Default GitHub repository |\n\n## Cloud Providers\n\n### Provider Comparison\n\n| Feature | AWS | Hetzner Cloud |\n|---------|-----|---------------|\n| **3x Agents (monthly)** | ~$110-120 | ~$18-22 |\n| **Instance Type** | t3.medium (2 vCPU, 4GB) | CX22 (2 vCPU, 4GB) |\n| **Storage** | ~$2.40/month per 30GB | Included |\n| **Data Transfer** | ~$5-10/month | 20TB included |\n| **Regions** | Global (25+) | EU \u0026 US (5 locations) |\n| **Setup Complexity** | Moderate (VPC, IAM) | Simple (API token) |\n\nUse Hetzner for development and cost savings (~80% cheaper). Use AWS for production or global reach.\n\n### What Gets Provisioned\n\nEach agent gets:\n- Cloud instance (EC2 or Hetzner server) with Ubuntu 24.04 LTS\n- Docker (for OpenClaw sandbox)\n- Node.js v22, OpenClaw CLI, Claude Code CLI, GitHub CLI\n- Tailscale VPN (encrypted mesh, no public ports)\n- Workspace files injected from `presets/`\n- Optional: Linear CLI (via Deno), Slack integration\n\nAll agents share a single VPC/network for cost optimization.\n\n## Dependencies\n\nYou need the following installed on your **local machine** before running `agent-army init`. The init wizard checks for these and will tell you what's missing.\n\n### Required (all providers)\n\n| Dependency | Why | Install |\n|------------|-----|---------|\n| **Node.js 18+** | Runtime for CLI and Pulumi program | [nodejs.org](https://nodejs.org/) |\n| **Pulumi CLI** | Infrastructure provisioning | [pulumi.com/docs/iac/download-install](https://www.pulumi.com/docs/iac/download-install/) |\n| **Pulumi Account** | State management and encrypted secrets | [app.pulumi.com/signup](https://app.pulumi.com/signup) |\n| **Tailscale** | Secure mesh VPN to reach your agents | [tailscale.com/download](https://tailscale.com/download) |\n\n### Required (provider-specific)\n\nPick one depending on where you want to deploy:\n\n| Provider | Dependency | Install |\n|----------|-----------|---------|\n| **AWS** | AWS CLI (configured with credentials) | [aws.amazon.com/cli](https://aws.amazon.com/cli/) — then run `aws configure` |\n| **Hetzner** | API token with Read \u0026 Write permissions | [console.hetzner.cloud](https://console.hetzner.cloud/) → Project → Security → API Tokens |\n\n### Tailscale Setup\n\nTailscale requires a few one-time setup steps:\n\n1. [Create an account](https://login.tailscale.com/start)\n2. [Enable HTTPS certificates](https://tailscale.com/kb/1153/enabling-https) (required for OpenClaw web UI)\n3. [Generate a reusable auth key](https://login.tailscale.com/admin/settings/keys) with tags\n4. Note your tailnet DNS name (e.g., `tail12345.ts.net`)\n\n### Installed on agents automatically\n\nThese are provisioned on the cloud instances via cloud-init — you do **not** need them locally:\n\n- Docker, Node.js v22, OpenClaw CLI, Claude Code CLI, GitHub CLI\n- Deno + Linear CLI (if Linear integration is enabled)\n- Tailscale (agent-side)\n\n## Required API Keys\n\n| Key | Required | Where to Get |\n|-----|----------|--------------|\n| **Anthropic Credentials** | Yes | [API Key](https://console.anthropic.com/) or OAuth token (`claude setup-token`) |\n| **Tailscale Auth Key** | Yes | [Tailscale Admin](https://login.tailscale.com/admin/settings/keys) (reusable, with tags) |\n| **Slack Bot Token** | No | [Slack API](https://api.slack.com/apps) — per agent |\n| **Linear API Token** | No | [Linear Settings](https://linear.app/settings/api) — per agent |\n| **GitHub Token** | No | [GitHub Settings](https://github.com/settings/tokens) — per agent |\n\n### Claude Code Authentication\n\nTwo authentication methods are supported:\n\n| Method | Token Format | Best For |\n|--------|-------------|----------|\n| **API Key** | `sk-ant-api03-...` | Pay-as-you-go API usage |\n| **OAuth Token** | `sk-ant-oat01-...` | Pro/Max subscription (flat rate) |\n\nThe system auto-detects which type you provide and sets the correct environment variable.\n\n## Updating \u0026 Redeploying\n\nAlways use a full teardown and rebuild to avoid stale Tailscale devices:\n\n```bash\nagent-army destroy\nagent-army deploy\n```\n\nOr with auto-confirm:\n\n```bash\nagent-army destroy -y \u0026\u0026 agent-army deploy -y\n```\n\nA simple `deploy` after changes can leave orphaned Tailscale devices and hostname conflicts. The destroy-then-deploy workflow ensures clean state.\n\n## Configuration\n\n### `agent-army.json`\n\nGenerated by `agent-army init`. This manifest drives the entire deployment:\n\n```json\n{\n  \"stackName\": \"dev\",\n  \"provider\": \"aws\",\n  \"region\": \"us-east-1\",\n  \"instanceType\": \"t3.medium\",\n  \"ownerName\": \"Your Name\",\n  \"agents\": [\n    {\n      \"name\": \"agent-pm\",\n      \"displayName\": \"Juno\",\n      \"role\": \"pm\",\n      \"preset\": \"pm\",\n      \"volumeSize\": 30\n    }\n  ]\n}\n```\n\n### Pulumi Config\n\nSecrets are stored encrypted in Pulumi config, set automatically by the init wizard. You can also manage them directly:\n\n```bash\npulumi config set --secret anthropicApiKey sk-ant-xxxxx\npulumi config set --secret tailscaleAuthKey tskey-auth-xxxxx\npulumi config set tailnetDnsName tail12345.ts.net\n```\n\n### Pulumi ESC\n\nFor more advanced secret management, use [Pulumi ESC](https://www.pulumi.com/docs/esc/). See `esc/agent-army-secrets.yaml.example` for the full template.\n\n## Project Structure\n\n```\nagent-army/\n├── cli/                    # CLI tool (commands, prompts, config management)\n│   ├── bin.ts              # Entry point (Commander.js)\n│   ├── commands/           # init, deploy, status, ssh, validate, destroy, list\n│   ├── lib/                # Config, prerequisites, Pulumi ops, UI helpers\n│   └── types.ts            # TypeScript types\n├── src/                    # Reusable Pulumi components\n│   └── components/\n│       ├── openclaw-agent.ts    # AWS EC2 agent component\n│       ├── hetzner-agent.ts     # Hetzner Cloud agent component\n│       ├── cloud-init.ts        # Cloud-init script generation\n│       └── config-generator.ts  # OpenClaw config builder\n├── presets/                # Agent role definitions \u0026 shared skills\n│   ├── base/               # Shared files for all agents\n│   ├── pm/                 # Juno (PM)\n│   ├── eng/                # Titus (Engineer)\n│   ├── tester/             # Scout (QA)\n│   └── skills/             # Reusable agent skills\n├── docs/                   # Mintlify documentation site\n├── esc/                    # Pulumi ESC secret templates\n├── scripts/                # Shell script helpers\n├── examples/               # Example deployments\n├── index.ts                # Main Pulumi stack program\n├── shared-vpc.ts           # Shared VPC component (AWS)\n└── Pulumi.yaml             # Pulumi project config\n```\n\n## Security\n\n- All agent ports bind to `127.0.0.1` — access is via **Tailscale only**\n- No public port exposure; Tailscale Serve proxies traffic\n- Token-based gateway authentication\n- Secrets encrypted via Pulumi config\n- SSH available as fallback for debugging\n\n## Troubleshooting\n\n### Agents not appearing in Tailscale\n\n1. Wait 3-5 minutes for cloud-init to complete\n2. Check logs: `agent-army ssh pm 'sudo cat /var/log/cloud-init-output.log | tail -100'`\n3. Verify your Tailscale auth key is valid and reusable\n\n### OpenClaw gateway not running\n\n```bash\nagent-army ssh pm 'openclaw gateway status'\nagent-army ssh pm 'journalctl -u openclaw -n 50'\nagent-army ssh pm 'openclaw gateway restart'\n```\n\n### SSH connection refused\n\n1. Check Tailscale is running locally: `tailscale status`\n2. Verify the agent appears in your tailnet\n3. Ensure you're using the correct tailnet DNS name\n\n### Pulumi state issues\n\n```bash\npulumi refresh    # Refresh state from actual infrastructure\npulumi cancel     # Force unlock if locked\n```\n\n## Development\n\nFor contributing to Agent Army itself:\n\n```bash\ngit clone https://github.com/stepandel/agent-army.git\ncd agent-army\npnpm install\npnpm build\npnpm run watch    # Watch mode\n```\n\n## License\n\nMIT\n\n## Related\n\n- [OpenClaw Documentation](https://docs.openclaw.ai/)\n- [Pulumi AWS Provider](https://www.pulumi.com/registry/packages/aws/)\n- [Pulumi Hetzner Provider](https://www.pulumi.com/registry/packages/hcloud/)\n- [Pulumi ESC](https://www.pulumi.com/docs/esc/)\n- [Tailscale Documentation](https://tailscale.com/kb/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstepandel%2Fagent-army","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstepandel%2Fagent-army","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstepandel%2Fagent-army/lists"}