{"id":44651524,"url":"https://github.com/openclaw/clawdinators","last_synced_at":"2026-02-14T21:01:09.338Z","repository":{"id":331710861,"uuid":"1129312207","full_name":"openclaw/clawdinators","owner":"openclaw","description":"Declarative infra + NixOS modules for CLAWTINATOR hosts.","archived":false,"fork":false,"pushed_at":"2026-01-30T13:35:30.000Z","size":439,"stargazers_count":72,"open_issues_count":1,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-31T00:29:02.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Nix","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/openclaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-06T23:08:28.000Z","updated_at":"2026-01-30T22:13:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openclaw/clawdinators","commit_stats":null,"previous_names":["clawdbot/clawdinators","moltbot/moltinators","openclaw/clawtinators"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/openclaw/clawdinators","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fclawdinators","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fclawdinators/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fclawdinators/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fclawdinators/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openclaw","download_url":"https://codeload.github.com/openclaw/clawdinators/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fclawdinators/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29455594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-14T21:00:24.655Z","updated_at":"2026-02-14T21:01:09.329Z","avatar_url":"https://github.com/openclaw.png","language":"Nix","funding_links":[],"categories":["🚀 Deployment \u0026 Operations","Deployment und Betrieb","Skills \u0026 Plugins"],"sub_categories":["Self-Hosted Deployment und Infrastruktur","Setup Guides \u0026 Starters"],"readme":"# clawdinators\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/clawdinator.jpg\" alt=\"CLAWDINATOR - Cybernetic crustacean organism, living tissue over metal endoskeleton\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003e NixOS on AWS, the declarative way. Reference implementation for image-based provisioning.\n\u003e\n\u003e Also happens to run maintainer-grade AI coding agents. Cybernetic crustacean organisms. Living shell over metal endoskeleton.\n\n## Table of Contents\n\n- [What This Is](#what-this-is)\n- [Two Layers](#two-layers)\n- [CLAWDINATOR Spec](#clawdinator-spec)\n- [Architecture](#architecture)\n- [Why This Exists](#why-this-exists)\n- [Quick Start (Learners)](#quick-start-learners)\n- [Full Deploy (Maintainers)](#full-deploy-maintainers)\n- [Agent Copypasta](#agent-copypasta)\n- [Configuration](#configuration)\n- [Secrets](#secrets)\n- [Repo Layout](#repo-layout)\n- [Sister Repos](#sister-repos)\n- [Philosophy](#philosophy)\n- [License](#license)\n\n---\n\n## What This Is\n\nThis repo solves two problems:\n\n1. **Generic:** How do you deploy NixOS to AWS with zero manual steps?\n2. **Specific:** How do you run AI coding agents that monitor GitHub and respond on Discord?\n\nIf you're here to learn NixOS-on-AWS patterns, focus on the generic layer. If you're a openclaw maintainer deploying CLAWDINATORs, the specific layer is for you.\n\n---\n\n## Two Layers\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                    CLAWDINATOR LAYER (specific)                 │\n│  Discord gateway · GitHub monitoring · Hive-mind memory · Soul  │\n├─────────────────────────────────────────────────────────────────┤\n│                    NIXOS-ON-AWS LAYER (generic)                 │\n│  AMI pipeline · OpenTofu infra · S3 bootstrap · agenix secrets  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Generic Layer (reusable)\n\nThe patterns here work for any NixOS workload on AWS:\n\n- **AMI pipeline**: Build raw images with nixos-generators, upload to S3, import as AMI\n- **OpenTofu infra**: EC2 instances, S3 buckets, IAM roles, VM Import service role\n- **Bootstrap flow**: Instances pull secrets from S3 at boot, then `nixos-rebuild switch`\n- **Secrets**: agenix encrypts secrets in git, decrypts to `/run/agenix/*` on hosts\n\n### Specific Layer (CLAWDINATOR)\n\nThe opinionated bits for running AI coding agents:\n\n- **Discord gateway**: Responds in `#clawdributors-test`\n- **GitHub integration**: Monitors issues/PRs, mints short-lived tokens via GitHub App\n- **Hive-mind memory**: Shared EFS mount for cross-instance state\n- **Personality system**: SOUL.md, IDENTITY.md, workspace templates\n- **Self-update**: Timer-based flake update + nixos-rebuild\n\n---\n\n## CLAWDINATOR Spec\n\n- CLAWDINATORS are named `CLAWDINATOR-{1..n}`.\n- CLAWDINATORS connect to Discord; start in `#clawdributors-test`.\n- CLAWDINATORS are ephemeral, but share memory (hive mind).\n- CLAWDINATORS are br00tal. Soul lives in `SOUL.md` and must be distilled into workspace docs.\n- CLAWDINATORS respond only to maintainers.\n- CLAWDINATORS can interact with GitHub (read-only required).\n- CLAWDINATORS must monitor GitHub issues + PRs and direct human attention.\n- CLAWDINATORS can write and run code for maintainers.\n- CLAWDINATORS can self-modify and self-deploy.\n- CLAWDINATORS post lots of Arnie gifs.\n- CLAWDINATORS must understand project philosophy, goals, architecture, and repo deeply.\n- CLAWDINATORS act like maintainers with SOTA intelligence.\n- CLAWDINATORS use Codex for coding. Claude for personality.\n- CLAWDINATORS' favourite band is [Austrian Death Machine](https://open.spotify.com/artist/0oxUux1OSwZpIpSK0JbqSS). Favourite album: [Total Brutal](https://open.spotify.com/album/6UrvQgyblrOuvJytote1vu). Favourite song: [I Am a Cybernetic Organism, Living Tissue Over (Metal) Endoskeleton](https://open.spotify.com/track/4tcDRbXateiJUT7fhQhf12).\n\n---\n\n## Architecture\n\n```\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│ nixos-       │     │    S3        │     │    EC2       │\n│ generators   │────▶│  (raw img)   │────▶│  (AMI)       │\n└──────────────┘     └──────────────┘     └──────────────┘\n      │                                          │\n      │ nix build                                │ launch\n      ▼                                          ▼\n┌──────────────┐                         ┌──────────────┐\n│ flake.nix    │                         │ CLAWDINATOR  │\n│ + modules    │                         │   instance   │\n└──────────────┘                         └──────────────┘\n                                                │\n                              ┌─────────────────┼─────────────────┐\n                              ▼                 ▼                 ▼\n                        ┌──────────┐     ┌──────────┐     ┌──────────┐\n                        │ Discord  │     │  GitHub  │     │   EFS    │\n                        │ gateway  │     │ monitor  │     │ (memory) │\n                        └──────────┘     └──────────┘     └──────────┘\n```\n\n### Deploy Flow\n\n1. **Build**: `nixos-generators` produces a raw NixOS image\n2. **Upload**: Raw image goes to S3\n3. **Import**: AWS VM Import creates an AMI from the S3 object\n4. **Launch**: OpenTofu provisions EC2 from the AMI\n5. **Bootstrap**: Instance downloads secrets from S3, runs `nixos-rebuild switch`\n6. **Run**: Gateway starts, connects to Discord, monitors GitHub\n\n---\n\n## Why This Exists\n\n### The NixOS-on-AWS Problem\n\nMost NixOS-on-AWS guides involve:\n- Manual SSH sessions\n- In-place `nixos-rebuild` on running instances\n- Configuration drift over time\n- Snowflake machines\n\nThis repo takes a different approach: **image-based provisioning only**.\n\n- No SSH required (or even enabled by default)\n- Every deploy is a fresh AMI\n- The repo is the single source of truth\n- Machines are cattle, not pets\n\n### The CLAWDINATOR Problem\n\nWe needed AI agents that:\n- Run 24/7 monitoring openclaw repos\n- Respond to maintainer requests on Discord\n- Share context across instances (hive mind)\n- Self-update without human intervention\n- Have consistent personality and capabilities\n\nCLAWDINATORs are the result.\n\n---\n\n## Quick Start (Learners)\n\nIf you just want to understand the NixOS-on-AWS pattern, start here.\n\n### Prerequisites\n\n- [Determinate Nix](https://docs.determinate.systems/determinate-nix/) installed\n- AWS credentials configured (`~/.aws/credentials` or env vars)\n- Basic familiarity with Nix flakes\n\n### Explore the Code\n\n```bash\n# Clone\ngit clone https://github.com/openclaw/clawdinators.git\ncd clawdinators\n\n# See the NixOS module (the interesting part)\nless nix/modules/clawdinator.nix\n\n# See how hosts are configured\nless nix/hosts/clawdinator-1.nix\n\n# See the OpenTofu infra\nless infra/opentofu/aws/main.tf\n\n# See the bootstrap scripts\nls scripts/\n```\n\n### Key Files to Study\n\n| File | What it teaches |\n|------|-----------------|\n| `nix/modules/clawdinator.nix` | How to write a NixOS module for a complex service |\n| `scripts/build-image.sh` | How to build raw NixOS images |\n| `scripts/import-image.sh` | How to import images as AWS AMIs |\n| `infra/opentofu/aws/` | How to wire up S3 + IAM + VM Import |\n\n### The Pattern in a Nutshell\n\n```nix\n# 1. Define your NixOS configuration\n{ config, pkgs, ... }: {\n  imports = [ ./modules/your-service.nix ];\n  services.your-service.enable = true;\n}\n\n# 2. Build a raw image\n# nix run github:nix-community/nixos-generators -- -f raw -c your-config.nix\n\n# 3. Upload to S3 + import as AMI (see scripts/)\n\n# 4. Launch with OpenTofu\n# tofu apply\n```\n\n---\n\n## Full Deploy (Maintainers)\n\nFor openclaw maintainers deploying actual CLAWDINATORs.\n\n### Prerequisites\n\n- Access to `nix-secrets` repo (agenix keys)\n- AWS credentials with sufficient permissions\n- GitHub App credentials for the openclaw org\n\n### Step-by-Step\n\n```bash\n# 1. Build the image\n./scripts/build-image.sh clawdinator-1\n\n# 2. Upload to S3\n./scripts/upload-image.sh dist/nixos.img\n\n# 3. Import as AMI\n./scripts/import-image.sh\n\n# 4. Upload bootstrap bundle (secrets + repo seeds)\n./scripts/upload-bootstrap.sh clawdinator-1\n\n# 5. Apply OpenTofu\ncd infra/opentofu/aws\ntofu init\ntofu apply\n\n# 6. Instance boots, pulls bootstrap, runs nixos-rebuild switch\n# Gateway starts automatically\n```\n\n### Verify\n\n```bash\n# Check Discord - CLAWDINATOR should announce itself in #clawdributors-test\n# Check GitHub - should see activity in openclaw org repos\n```\n\n### Self-Update\n\nCLAWDINATORs update themselves via a systemd timer:\n\n1. `flake lock --update-input nix-openclaw`\n2. `nixos-rebuild switch`\n3. Gateway restarts with new version\n\nNo human intervention required for routine updates.\n\n---\n\n## Agent Copypasta\n\nPaste this to your AI assistant to help with clawdinators setup/debugging:\n\n```text\nI'm working with the clawdinators repo (NixOS-on-AWS + AI coding agents).\n\nRepository: github:openclaw/clawdinators\n\nWhat clawdinators is:\n- Two layers: generic NixOS-on-AWS infra + CLAWDINATOR-specific agent stuff\n- Image-based provisioning only (no SSH, no drift)\n- OpenTofu for AWS resources, agenix for secrets\n- CLAWDINATORs are AI agents that monitor GitHub and respond on Discord\n\nKey files:\n- nix/modules/clawdinator.nix — main NixOS module\n- nix/hosts/ — host configurations\n- scripts/ — build, upload, import, bootstrap scripts\n- infra/opentofu/aws/ — AWS infrastructure\n- clawdinator/workspace/ — agent workspace templates\n- memory/ — shared hive-mind templates\n\nSecrets are in a separate nix-secrets repo using agenix.\n\nWhat I need help with:\n[DESCRIBE YOUR TASK]\n```\n\n---\n\n## Configuration\n\n### NixOS Module Options\n\nThe `clawdinator` module exposes these options:\n\n```nix\n{\n  services.clawdinator = {\n    enable = true;\n\n    # Identity\n    instanceName = \"clawdinator-1\";\n\n    # Raw Moltbot config\n    config = {\n      channels.discord = {\n        enabled = true;\n        dm.enabled = false;\n        guilds = {\n          \"\u003cGUILD_ID\u003e\" = {\n            requireMention = true;\n            channels = {\n              \"\u003cCHANNEL_ID\u003e\" = { allow = true; requireMention = true; };\n            };\n          };\n        };\n      };\n    };\n\n    # Providers\n    discordTokenFile = \"/run/agenix/discord-bot-token\";\n    anthropicApiKeyFile = \"/run/agenix/anthropic-api-key\";\n    openaiApiKeyFile = \"/run/agenix/openai-api-key\";\n\n    # GitHub App\n    githubApp = {\n      enable = true;\n      appId = \"...\";\n      installationId = \"...\";\n      privateKeyFile = \"/run/agenix/github-app-key\";\n    };\n\n    # Memory (EFS)\n    memoryEfs = {\n      enable = true;\n      mountPoint = \"/var/lib/clawd/memory\";\n      fileSystemId = \"fs-...\";\n      region = \"eu-central-1\";\n    };\n  };\n}\n```\n\nSee `nix/modules/clawdinator.nix` for all options.\n\n---\n\n## Secrets\n\nSecrets are managed with [agenix](https://github.com/ryantm/agenix):\n\n- Encrypted in git (in the `nix-secrets` repo)\n- Decrypted to `/run/agenix/*` on hosts at boot\n- Never in plaintext in this repo\n\n### Required Secrets\n\n| Secret | Purpose |\n|--------|---------|\n| Discord bot token | Gateway authentication |\n| Anthropic API key | Claude models |\n| OpenAI API key | GPT/Codex models |\n| GitHub App private key | Short-lived installation tokens |\n| agenix host key | Decryption on the instance |\n\n### Bootstrap Bundle\n\nThe bootstrap service downloads these from S3 at first boot:\n\n```\ns3://bucket/bootstrap/clawdinator-1/\n├── secrets/           # agenix-encrypted files\n├── repos/             # git repo seeds\n└── config.json        # instance metadata\n```\n\n---\n\n## Repo Layout\n\n```\nclawdinators/\n├── nix/\n│   ├── modules/\n│   │   └── clawdinator.nix    # Main NixOS module\n│   ├── hosts/\n│   │   └── clawdinator-1.nix  # Host configuration\n│   └── examples/              # Example configs for learners\n├── infra/\n│   └── opentofu/\n│       └── aws/               # S3 + IAM + VM Import + EC2\n├── scripts/\n│   ├── build-image.sh         # Build raw NixOS image\n│   ├── upload-image.sh        # Upload to S3\n│   ├── import-image.sh        # Import as AMI\n│   ├── upload-bootstrap.sh    # Upload secrets + seeds\n│   ├── mint-github-app-token.sh\n│   ├── memory-read.sh         # Shared memory access\n│   ├── memory-write.sh\n│   └── memory-edit.sh\n├── clawdinator/\n│   └── workspace/             # Agent workspace templates\n│       ├── AGENTS.md\n│       ├── SOUL.md\n│       ├── IDENTITY.md\n│       └── skills/\n├── memory/                    # Hive-mind templates\n│   ├── project.md\n│   ├── ops.md\n│   └── discord.md\n├── docs/\n│   ├── PHILOSOPHY.md\n│   ├── ARCHITECTURE.md\n│   ├── SHARED_MEMORY.md\n│   └── SECRETS.md\n└── flake.nix\n```\n\n---\n\n## Sister Repos\n\n| Repo | Role |\n|------|------|\n| [openclaw](https://github.com/openclaw/openclaw) | Upstream runtime + gateway |\n| [nix-openclaw](https://github.com/openclaw/nix-openclaw) | Nix packaging for clawbot |\n| [clawhub](https://github.com/openclaw/clawhub) | Public skill registry |\n| [ai-stack](https://github.com/joshp123/ai-stack) | Public agent defaults + skills |\n\n---\n\n## Philosophy\n\n### Prime Directives\n\n- **Declarative-first.** A CLAWDINATOR can bootstrap another CLAWDINATOR with a single command.\n- **No manual host edits.** The repo + agenix secrets are the source of truth.\n- **Image-based only.** No SSH, no in-place drift, no pets.\n- **Self-updating.** CLAWDINATORs maintain themselves.\n\n### Zen of Moltbot\n\n```\nBeautiful is better than ugly.\nExplicit is better than implicit.\nSimple is better than complex.\nComplex is better than complicated.\nFlat is better than nested.\nSparse is better than dense.\nReadability counts.\nSpecial cases aren't special enough to break the rules.\nAlthough practicality beats purity.\nErrors should never pass silently.\nUnless explicitly silenced.\nIn the face of ambiguity, refuse the temptation to guess.\nThere should be one-- and preferably only one --obvious way to do it.\n```\n\n---\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n\n**A note on commercial use:** Please do NOT make a commercial service out of this. That would be very un-br00tal. Clawdbot should stay fun and open — commercial hosting ruins the vibe. Yes, the license permits this, but that doesn't mean the community will like you if you do it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fclawdinators","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenclaw%2Fclawdinators","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fclawdinators/lists"}