create-ironclaws 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# IronClaws Kit
+
+Scaffold an IronClaws AI agent platform in under 5 minutes.
+
+```bash
+npx create-ironclaws my-workspace
+```
+
+The wizard walks you through Slack tokens, LiteLLM gateway, and your first agent's channel. It then starts OneCLI, registers credentials, builds the container image, and optionally starts IronClaws. Send `@Forge hello` and your guide agent responds.
+
+---
+
+## What you get
+
+Your first agent is **Forge** — a built-in guide that knows how IronClaws works and can help you build new agents directly from Slack. Ask it anything:
+
+> `@Forge how do I add a new agent?`
+> `@Forge explain how credentials work`
+> `@Forge build me an agent that monitors Jira`
+
+---
+
+## Adding more agents
+
+### Via Forge (recommended)
+Just describe what you want in Slack. Forge will draft the CLAUDE.md, show you the `agents.yaml` and `.env` entries, and tell you to restart.
+
+### Manually
+
+**1. Write the agent's identity** — create `groups/my-agent/CLAUDE.md`:
+```markdown
+# My Agent
+
+What this agent does in one sentence.
+
+## What you do
+Responsibilities.
+
+## How to respond
+Tone, format, constraints.
+```
+
+**2. Register it** — add to `agents.yaml`:
+```yaml
+  - folder: my-agent
+    name: "My Agent"
+    trigger: "@Argus"
+    channel_env: MY_AGENT_CHANNEL_ID
+    requires_trigger: false
+    onecli_secrets: [litellm]
+    onecli_id: <python3 -c "import uuid; print(uuid.uuid4())">
+```
+
+**3. Set the channel** — add to `.env`:
+```
+MY_AGENT_CHANNEL_ID=C...
+```
+
+**4. Restart IronClaws** — the agent auto-registers, its channel is added to the allowlist, and it's live.
+
+---
+
+## Giving agents tools and credentials
+
+Edit `agent-credentials.yaml` to control what each agent can access:
+
+```yaml
+agents:
+  my-agent:
+    skills: []
+    tools: [jira_tool.py]       # Python tools from container/tools/
+    config:
+      - JIRA_BASE_URL           # non-secret config from .env
+```
+
+For service credentials (Jira, Slack, etc.) add them to `onecli_secrets` in `agents.yaml`. OneCLI injects them as Authorization headers — agents never see the raw keys.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- Docker
+- A Slack app with Socket Mode and a bot token
+- A LiteLLM gateway (or Anthropic API access)
+
+## Manual setup (without the wizard)
+
+```bash
+git clone https://github.com/ardoq/ironclaws-kit my-workspace
+cd my-workspace
+cp .env.example .env          # fill in your values
+docker compose up -d          # start OneCLI infrastructure
+npm ci
+cd container && ./build.sh && ./build-argus.sh && cd ..
+npm run dev
+```
+
+## Production note
+
+Network enforcement (iptables) is Linux-only. On macOS/Windows dev machines, agents have unrestricted outbound access. Deploy on Linux for production.

package/bin/create.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+/**
+ * create-ironclaws — Interactive setup wizard for IronClaws
+ *
+ * Usage:
+ *   npx create-ironclaws [project-name]
+ *   npx create-ironclaws@latest my-it-ops
+ */
+
+import prompts from 'prompts';
+import kleur from 'kleur';
+import fs from 'fs';
+import path from 'path';
+import { execSync, spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+
+// ── Utilities ──────────────────────────────────────────────────────────────────
+
+function log(msg) { console.log(msg); }
+function success(msg) { console.log(kleur.green('  ✓ ') + msg); }
+function info(msg) { console.log(kleur.cyan('  → ') + msg); }
+function warn(msg) { console.log(kleur.yellow('  ⚠ ') + msg); }
+function fatal(msg) { console.error(kleur.red('  ✗ ') + msg); process.exit(1); }
+
+function hasCommand(cmd) {
+  try { execSync(`which ${cmd}`, { stdio: 'pipe' }); return true; } catch { return false; }
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function waitForOneCLI(maxWaitMs = 60000) {
+  const start = Date.now();
+  info('Waiting for OneCLI to be ready...');
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      execSync('curl -sf http://localhost:10254/api/secrets > /dev/null 2>&1', { stdio: 'pipe' });
+      return true;
+    } catch {
+      execSync('sleep 2', { stdio: 'pipe' });
+    }
+  }
+  return false;
+}
+
+function registerOneCLISecret(name, hostPattern, headerName, value, apiKey) {
+  const authHeader = apiKey ? `-H "Authorization: Bearer ${apiKey}"` : '';
+
+  // Delete existing
+  try {
+    const existing = execSync(
+      `curl -sf ${authHeader} http://localhost:10254/api/secrets`,
+      { encoding: 'utf-8', stdio: 'pipe' }
+    );
+    const secrets = JSON.parse(existing);
+    const match = secrets.find(s => s.name === name);
+    if (match) {
+      execSync(`curl -sf -X DELETE ${authHeader} http://localhost:10254/api/secrets/${match.id}`, { stdio: 'pipe' });
+    }
+  } catch { /* ok */ }
+
+  // Create
+  const body = JSON.stringify({
+    name,
+    type: 'generic',
+    value,
+    hostPattern,
+    injectionConfig: { headerName },
+  });
+
+  execSync(
+    `curl -sf -X POST ${authHeader} http://localhost:10254/api/secrets -H "Content-Type: application/json" -d '${body}'`,
+    { stdio: 'pipe' }
+  );
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log();
+  console.log(kleur.bold().white('  ✦ IronClaws Setup'));
+  console.log(kleur.gray('  AI agents over Slack for IT operations'));
+  console.log();
+
+  // Check prerequisites
+  if (!hasCommand('node')) fatal('Node.js is required. Install from nodejs.org');
+  if (!hasCommand('docker')) fatal('Docker is required. Install from docs.docker.com');
+
+  // Project directory
+  const projectArg = process.argv[2];
+  let projectDir;
+
+  if (projectArg) {
+    projectDir = path.resolve(process.cwd(), projectArg);
+  } else {
+    const { dir } = await prompts({
+      type: 'text',
+      name: 'dir',
+      message: 'Project directory',
+      initial: './my-ironclaws',
+    });
+    if (!dir) process.exit(0);
+    projectDir = path.resolve(process.cwd(), dir);
+  }
+
+  if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
+    const { ok } = await prompts({
+      type: 'confirm',
+      name: 'ok',
+      message: `${projectDir} already exists and is not empty. Continue?`,
+      initial: false,
+    });
+    if (!ok) process.exit(0);
+  }
+
+  console.log();
+
+  // Core config
+  const core = await prompts([
+    {
+      type: 'text',
+      name: 'assistantName',
+      message: 'What should your assistant be called?',
+      initial: 'Argus',
+    },
+    {
+      type: 'text',
+      name: 'slackBotToken',
+      message: 'Slack Bot Token (xoxb-...)',
+      validate: v => v.startsWith('xoxb-') ? true : 'Must start with xoxb-',
+    },
+    {
+      type: 'text',
+      name: 'slackAppToken',
+      message: 'Slack App Token (xapp-...)',
+      validate: v => v.startsWith('xapp-') ? true : 'Must start with xapp-',
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  console.log();
+  log(kleur.gray('  LiteLLM gateway (routes Claude API calls through your proxy)'));
+
+  const llm = await prompts([
+    {
+      type: 'text',
+      name: 'litellmUrl',
+      message: 'LiteLLM gateway URL',
+      initial: 'https://your-litellm-gateway.example.com',
+    },
+    {
+      type: 'text',
+      name: 'litellmToken',
+      message: 'LiteLLM auth token (sk-...)',
+    },
+    {
+      type: 'text',
+      name: 'anthropicModel',
+      message: 'Model name (must match LiteLLM deployment)',
+      initial: 'anthropic-claude-opus-4-6',
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  // Forge — the built-in guide agent
+  console.log();
+  log(kleur.gray('  Forge is your built-in guide — it knows how IronClaws works and can'));
+  log(kleur.gray('  help you build new agents directly from Slack (@Forge add a new agent).'));
+  console.log();
+
+  const agent = await prompts([
+    {
+      type: 'text',
+      name: 'agentName',
+      message: 'Forge display name (shown in Slack)',
+      initial: 'Forge',
+    },
+    {
+      type: 'text',
+      name: 'agentFolder',
+      message: 'Forge folder name',
+      initial: 'forge',
+      validate: v => /^[a-z0-9-]+$/.test(v) ? true : 'Lowercase letters, numbers and hyphens only',
+    },
+    {
+      type: 'text',
+      name: 'channelId',
+      message: 'Slack channel ID for Forge (right-click channel → View channel details)',
+      validate: v => v.startsWith('C') || v.startsWith('D') ? true : 'Should start with C (channel) or D (DM)',
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  // Optional
+  console.log();
+  const optional = await prompts([
+    {
+      type: 'confirm',
+      name: 'startInfra',
+      message: 'Start OneCLI infrastructure now? (docker compose up -d)',
+      initial: true,
+    },
+    {
+      type: 'confirm',
+      name: 'buildImage',
+      message: 'Build the agent container image? (takes ~2 min)',
+      initial: true,
+    },
+    {
+      type: 'confirm',
+      name: 'startNano',
+      message: 'Start NanoClaw now?',
+      initial: true,
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  // ── Generate project ─────────────────────────────────────────────────────────
+
+  console.log();
+  log(kleur.bold('  Creating your project...'));
+  console.log();
+
+  // Copy template
+  copyDir(TEMPLATE_DIR, projectDir);
+  success('Template copied');
+
+  // Rename forge folder to user's chosen name
+  const exampleDir = path.join(projectDir, 'groups', 'forge');
+  const agentDir = path.join(projectDir, 'groups', agent.agentFolder);
+  if (fs.existsSync(exampleDir)) {
+    fs.renameSync(exampleDir, agentDir);
+  }
+
+  // Generate .env
+  const envContent = [
+    `# IronClaws — generated by create-ironclaws`,
+    ``,
+    `# ── NanoClaw core ─────────────────────────────────────────────────────────────`,
+    `ASSISTANT_NAME=${core.assistantName}`,
+    `CONTAINER_IMAGE=argus-claude:latest`,
+    ``,
+    `# ── Slack ─────────────────────────────────────────────────────────────────────`,
+    `SLACK_BOT_TOKEN=${core.slackBotToken}`,
+    `SLACK_APP_TOKEN=${core.slackAppToken}`,
+    ``,
+    `# ── LiteLLM / Anthropic ───────────────────────────────────────────────────────`,
+    `ANTHROPIC_BASE_URL=${llm.litellmUrl}`,
+    `ANTHROPIC_BEDROCK_BASE_URL=${llm.litellmUrl}/bedrock`,
+    `ANTHROPIC_AUTH_TOKEN=${llm.litellmToken}`,
+    ``,
+    `CLAUDE_CODE_USE_BEDROCK=1`,
+    `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1`,
+    `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000`,
+    ``,
+    `ANTHROPIC_MODEL=${llm.anthropicModel}`,
+    `ANTHROPIC_SMALL_FAST_MODEL=${llm.anthropicModel}`,
+    `ANTHROPIC_DEFAULT_OPUS_MODEL=${llm.anthropicModel}`,
+    `ANTHROPIC_DEFAULT_SONNET_MODEL=${llm.anthropicModel}`,
+    `ANTHROPIC_DEFAULT_HAIKU_MODEL=${llm.anthropicModel}`,
+    ``,
+    `# ── Agent channel IDs ─────────────────────────────────────────────────────────`,
+    `${agent.agentFolder.toUpperCase().replace(/-/g, '_')}_CHANNEL_ID=${agent.channelId}`,
+  ].join('\n');
+
+  fs.writeFileSync(path.join(projectDir, '.env'), envContent);
+  success('.env generated');
+
+  // Generate agents.yaml
+  const agentEnvKey = `${agent.agentFolder.toUpperCase().replace(/-/g, '_')}_CHANNEL_ID`;
+  const agentsYaml = [
+    `# agents.yaml — Your agent fleet`,
+    `# Add more agents here. Set their channel ID in .env.`,
+    `# NanoClaw auto-registers agents on startup.`,
+    ``,
+    `agents:`,
+    `  - folder: ${agent.agentFolder}`,
+    `    name: "${agent.agentName}"`,
+    `    trigger: "@${core.assistantName}"`,
+    `    channel_env: ${agentEnvKey}`,
+    `    requires_trigger: false`,
+    `    onecli_secrets: [litellm]`,
+    `    onecli_id: ${generateUUID()}`,
+  ].join('\n');
+
+  fs.writeFileSync(path.join(projectDir, 'agents.yaml'), agentsYaml);
+
+  // Update agent-credentials.yaml with actual agent name
+  const credPath = path.join(projectDir, 'agent-credentials.yaml');
+  if (fs.existsSync(credPath)) {
+    const cred = fs.readFileSync(credPath, 'utf-8')
+      .replace('forge:', `${agent.agentFolder}:`);
+    fs.writeFileSync(credPath, cred);
+  }
+
+  success('Configuration generated');
+
+  // Start infrastructure
+  if (optional.startInfra) {
+    console.log();
+    info('Starting OneCLI infrastructure...');
+    const result = spawnSync('docker', ['compose', 'up', '-d'], {
+      cwd: projectDir,
+      stdio: 'inherit',
+    });
+    if (result.status !== 0) {
+      warn('docker compose up failed — start it manually: docker compose up -d');
+    } else {
+      success('OneCLI infrastructure started');
+
+      // Register LiteLLM secret
+      if (llm.litellmToken && llm.litellmUrl) {
+        info('Registering LiteLLM credential with OneCLI...');
+        const ready = waitForOneCLI();
+        if (ready) {
+          try {
+            const host = llm.litellmUrl.replace(/^https?:\/\//, '').split('/')[0];
+            registerOneCLISecret('litellm', host, 'Authorization', `Bearer ${llm.litellmToken}`, '');
+            success(`LiteLLM secret registered for ${host}`);
+          } catch (e) {
+            warn(`Could not register secret automatically. Run manually: bash ${path.join(projectDir, 'scripts/setup-onecli-secrets.sh')}`);
+          }
+        } else {
+          warn('OneCLI not ready in time — run setup-onecli-secrets.sh manually after it starts');
+        }
+      }
+    }
+  }
+
+  // Install dependencies
+  console.log();
+  info('Installing dependencies...');
+  spawnSync('npm', ['ci'], { cwd: projectDir, stdio: 'inherit' });
+  success('Dependencies installed');
+
+  // Build container image
+  if (optional.buildImage) {
+    console.log();
+    info('Building container image (this takes ~2 minutes)...');
+    const b1 = spawnSync('bash', ['./container/build.sh'], { cwd: projectDir, stdio: 'inherit' });
+    const b2 = spawnSync('bash', ['./container/build-argus.sh'], { cwd: projectDir, stdio: 'inherit' });
+    if (b1.status === 0 && b2.status === 0) {
+      success('Container image built: argus-claude:latest');
+    } else {
+      warn('Image build failed — run: cd container && ./build.sh && ./build-argus.sh');
+    }
+  }
+
+  // Done!
+  console.log();
+  console.log(kleur.bold().green('  ✦ Setup complete!'));
+  console.log();
+
+  if (optional.startNano) {
+    info(`Starting NanoClaw in ${projectDir}...`);
+    console.log();
+    spawnSync('npm', ['run', 'dev'], { cwd: projectDir, stdio: 'inherit' });
+  } else {
+    log(`  To start NanoClaw:`);
+    log(kleur.cyan(`    cd ${path.relative(process.cwd(), projectDir)} && npm run dev`));
+    console.log();
+    log(`  Then send this in Slack:`);
+    log(kleur.cyan(`    @${core.assistantName} hello`));
+    console.log();
+    if (!optional.startInfra) {
+      log(`  Don't forget to start OneCLI first:`);
+      log(kleur.cyan(`    cd ${path.relative(process.cwd(), projectDir)} && docker compose up -d`));
+      console.log();
+    }
+    log(kleur.gray(`  ⚠  Network enforcement (iptables) is only active on Linux.`));
+    log(kleur.gray(`     On macOS/Windows, agents have unrestricted network access.`));
+    log(kleur.gray(`     Use a Linux VM for production deployments.`));
+  }
+
+  console.log();
+}
+
+function generateUUID() {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+  });
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-ironclaws",
+  "version": "1.0.0",
+  "description": "Create an IronClaws AI agent platform in seconds",
+  "type": "module",
+  "bin": {
+    "create-ironclaws": "bin/create.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "test": "node bin/create.js --dry-run"
+  },
+  "dependencies": {
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "slack",
+    "it-ops",
+    "claude",
+    "nanoclaw",
+    "ironclaws"
+  ],
+  "license": "MIT"
+}

package/template/.env.example

@@ -0,0 +1,38 @@
+# IronClaws configuration
+# Generated by: npx create-ironclaws
+# Fill in all values, then run: docker compose up -d && npm run dev
+
+# ── NanoClaw core ─────────────────────────────────────────────────────────────
+ASSISTANT_NAME=Argus
+CONTAINER_IMAGE=argus-claude:latest
+
+# ── Slack ─────────────────────────────────────────────────────────────────────
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_APP_TOKEN=xapp-...
+
+# ── LiteLLM / Anthropic ───────────────────────────────────────────────────────
+ANTHROPIC_BASE_URL=https://your-litellm-gateway.example.com
+ANTHROPIC_BEDROCK_BASE_URL=https://your-litellm-gateway.example.com/bedrock
+ANTHROPIC_AUTH_TOKEN=sk-...
+
+CLAUDE_CODE_USE_BEDROCK=1
+CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
+CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
+
+ANTHROPIC_MODEL=anthropic-claude-opus-4-6
+ANTHROPIC_SMALL_FAST_MODEL=anthropic-claude-opus-4-6
+ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic-claude-opus-4-6
+ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic-claude-sonnet-4-6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic.claude-haiku-4-5
+
+# ── GitHub (optional — needed for agents that create PRs) ─────────────────────
+# GITHUB_APP_ID=
+# GITHUB_APP_INSTALLATION_ID=
+# GITHUB_REPO=owner/repo
+
+# ── OneCLI API key (if your OneCLI instance has auth enabled) ─────────────────
+# ONECLI_API_KEY=oc_...
+
+# ── Agent channel IDs ─────────────────────────────────────────────────────────
+# Right-click a channel in Slack → View channel details → scroll to bottom
+FORGE_CHANNEL_ID=C...   # Forge — your IronClaws guide agent

package/template/CLAUDE.md

@@ -0,0 +1,104 @@
+# NanoClaw — Ardoq IT Ops Agent Platform
+
+Internal deployment of NanoClaw. Hosts the Ardoq IT agent fleet over Slack.
+
+## Architecture
+
+Single Node.js host process. Each registered agent gets its own Docker container (isolated filesystem + memory) spawned on demand. Agents communicate back via IPC files. All agents share one Docker image: `argus-claude:latest`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Main loop: message routing, agent invocation, state |
+| `src/channels/slack.ts` | Slack channel integration (Socket Mode) |
+| `src/container-runner.ts` | Spawns containers with correct mounts and env vars |
+| `src/ipc.ts` | IPC file watcher — agents write here to send messages / schedule tasks |
+| `src/task-scheduler.ts` | Cron-based task scheduling |
+| `src/db.ts` | SQLite: messages, groups, sessions, tasks |
+| `src/config.ts` | Trigger patterns, paths, env var loading |
+| `src/sender-allowlist.ts` | Per-channel sender filtering |
+| `groups/{name}/CLAUDE.md` | Per-agent identity and instructions |
+| `container/Dockerfile.argus` | Agent container image definition |
+| `container/tools/` | Python tools available inside containers |
+| `container/skills/` | Shared skills available to all agents |
+
+## Agent Fleet
+
+| Agent | Folder | Channel | Purpose |
+|-------|--------|---------|---------|
+| Argus Alert | `argus-alert` | Alert channel | Monitors alerts, investigates incidents, raises fix PRs |
+| Argus Deps | `argus-deps` | Deps channel | Manages Dependabot alerts, bumps packages |
+| Byte | `byte` | IT standup | Team standup agent, team memory |
+| Byte IT Internal | `byte-it-internal` | IT internal | Silent reader, writes to Byte's MEMORY.md |
+| Ticket Creator | `ticket-creator` | Ticket channel | Creates Jira tickets from Slack conversation |
+| Jira Worker | `jira-worker` | Worker channel | Picks up IAI tickets, implements, raises PRs |
+| Global Claw | `global-claw` | DM (Sewnet only) | Meta-agent: manages all other agents |
+
+## Container Image
+
+All agents use `argus-claude:latest`. Built with:
+```bash
+cd container && ./build-argus.sh
+```
+
+Set `CONTAINER_IMAGE=argus-claude:latest` in `.env`.
+
+## Tools Available Inside Containers
+
+Located in `container/tools/` — baked into the image:
+- `elastic_query.py` — Kibana/Elastic log querying
+- `jira_tool.py` — Jira CRUD (get, search, create, update, comment, assign)
+- `gdrive_tool.py` — Google Drive transcript reading
+- `slack_history_tool.py` — Slack channel history fetching
+
+## Skills Available Inside Containers
+
+Located in `container/skills/` — loaded at runtime:
+- `agent-browser` — web browsing
+- `capabilities` — list available skills
+- `slack-formatting` — Slack mrkdwn formatting reference
+- `status` — system health check
+- `agent-status` — dashboard of all agents
+- `edit-agent` — collaborative CLAUDE.md editing
+
+## Runtime Config
+
+Key env vars (set in `.env`):
+```
+SLACK_BOT_TOKEN      Slack bot token (xoxb-...)
+SLACK_APP_TOKEN      Slack app-level token (xapp-...)
+GITHUB_TOKEN         GitHub PAT for raising PRs
+GITHUB_APP_ID        GitHub App ID (for token generation)
+ELASTIC_BASE_URL     Kibana base URL
+ELASTIC_API_KEY      Kibana API key
+JIRA_BASE_URL        https://ardoqcom.atlassian.net
+JIRA_EMAIL           Jira account email
+JIRA_API_TOKEN       Jira API token
+JIRA_PROJECT_KEY     IAI
+CONTAINER_IMAGE      argus-claude:latest
+```
+
+## Security
+
+- Mount allowlist: `~/.config/nanoclaw/mount-allowlist.json` — controls what host paths containers can access
+- Sender allowlist: `~/.config/nanoclaw/sender-allowlist.json` — per-channel sender filtering, outside project root (tamper-proof)
+- Global Claw DM is restricted to Sewnet only (U04S2VA1CU8) at allowlist level
+- `github-app.pem` is gitignored — never commit
+
+## Running
+
+```bash
+npm run dev          # Development (hot reload)
+npm run build        # Compile TypeScript
+npm start            # Production
+```
+
+## First-Time Setup
+
+1. Copy `.env.example` to `.env` and fill in all values
+2. Run `./setup-agents.sh` to register all agents in the SQLite database
+3. Update `~/.config/nanoclaw/sender-allowlist.json` with channel IDs
+4. Update `~/.config/nanoclaw/mount-allowlist.json` for Global Claw repo access
+5. Build the container: `cd container && ./build-argus.sh`
+6. Start: `npm run dev`