Guardian Core Development & Infrastructure Reference

Comprehensive reference for all development, infrastructure, and operations concerns. Cross-references /debug for container issues and /self-update for deploy commands.

1. Dev Environment

Bootstrap

scripts/bootstrap.sh   # Idempotent; installs Nix, direnv, pins flake.lock, runs bun install

Works on macOS (Apple Silicon/Intel), NixOS, and non-NixOS Linux. Detects NixOS via /etc/NIXOS.

Nix devShell Contents

Activated automatically via .envrc (use flake) + direnv, or manually with nix develop.

Shell Environment

Set by shellHook in flake.nix:

PATH prepends: $PWD/node_modules/.bin, $MIX_HOME/bin, $MIX_HOME/escripts
MIX_HOME = $PWD/.nix-mix
HEX_HOME = $PWD/.nix-hex
BUN_VERSION_PIN = 1.3.8

direnv Integration

2. Nix Flake Architecture

Source: flake.nix

inputs:
  nixpkgs        → github:NixOS/nixpkgs/nixpkgs-unstable
  flake-utils    → github:numtide/flake-utils
  sops-nix       → github:Mic92/sops-nix
  private-config → path:/etc/guardian-private  (flake = false)

Outputs

Private Config Pattern

Nix flakes can only see git-tracked files. Host-specific config lives at /etc/guardian-private/ (external flake input, flake = false):

hardware-configuration.nix (tracked) delegates to private-config + "/hardware-configuration.private.nix".

Updating Flake Inputs

nix flake update                    # Update all inputs
nix flake lock --update-input nixpkgs  # Update only nixpkgs

Pitfall: After updating nixpkgs, rebuild to verify nothing breaks before deploying.

3. NixOS System Configuration

Host: rumi-vps (167.114.144.68, x86_64-linux)

Module Import Chain

configuration.nix imports:

1. •./hardware-configuration.nix → delegates to private-config
2. •./services/guardian-core.nix
3. •./services/rumi-platform.nix
4. •./services/server.nix
5. •./sops-secrets.nix
6. •private-config + "/private.nix"

System Settings

User: rumi

SSH

Critical: Port 22 MUST remain in allowedTCPPorts — SSH is via public IP, not Tailscale only.

Caddy Reverse Proxy

services.caddy.enable = true;
services.caddy.globalConfig = ''acme_ca https://acme-v02.api.letsencrypt.org/directory'';

Virtual host definitions live in private.nix (host-specific domains).

Tailscale

services.tailscale.enable = true;

Firewall

System Packages (VPS)

git, curl, htop, jq, bun, nodejs_22, docker-client

Other

4. Secrets Management (sops-nix + age)

Architecture

.sops.yaml                          # Creation rules: path_regex → age keys
infra/nixos/secrets/*.env           # Encrypted dotenv files (tracked in git)
/var/lib/sops-nix/key.txt           # age private key (0400 root:root)
/run/secrets/*                      # Decrypted at runtime to tmpfs

Security Controls

Encrypted Secret Files

All defined in infra/nixos/sops-secrets.nix with format = "dotenv".

.sops.yaml

keys:
  - &rumi-vps age1gngjsgsqhdjre3yjnk2dqregh3dt7n38273uxsjx52xqszz3jujqfcthcp
creation_rules:
  - path_regex: infra/nixos/secrets/.*\.env$
    key_groups:
      - age:
          - *rumi-vps

Editing Secrets

age and sops are NOT installed system-wide on the VPS. Use nix-shell:

nix-shell -p sops age --run \
  "SOPS_AGE_KEY_FILE=/var/lib/sops-nix/key.txt sops infra/nixos/secrets/<file>.env"

Adding a New Secret File

1. •Create the encrypted file:
   bash

   nix-shell -p sops age --run \
     "SOPS_AGE_KEY_FILE=/var/lib/sops-nix/key.txt sops infra/nixos/secrets/new-service.env"
   

2. •Add entry in infra/nixos/sops-secrets.nix:
   nix

   sops.secrets."new-service-env" = {
     sopsFile = ./secrets/new-service.env;
     format = "dotenv";
     owner = "rumi";
     group = "users";
     mode = "0400";
   };
   

3. •Reference in service unit: EnvironmentFile = config.sops.secrets."new-service-env".path;
4. •Commit the encrypted .env file to git.

Fail-Closed Pattern

All three service .nix files use a throw guard:

envFile =
  if builtins.hasAttr envSecretName config.sops.secrets then
    config.sops.secrets.${envSecretName}.path
  else
    throw "<service> requires sops secret ${envSecretName}; do not use plaintext .env files.";

This prevents NixOS from building if the secret definition is missing — fail-closed.

Key Management

5. Systemd Services

Service Comparison

Hardening (SP-SECRET-002, all services)

NoNewPrivileges = true;
PrivateTmp = true;
ProtectSystem = "strict";

Key: ProtectSystem = "strict" makes the entire filesystem read-only except paths listed in ReadWritePaths.

guardian-core Environment Variables

Set in services/guardian-core.nix:

Additional vars come from the sops EnvironmentFile (API keys, tokens).

Systemd Service Template (non-NixOS)

infra/systemd/guardian-core.service is a template with {{PLACEHOLDERS}} resolved by mix deploy.brain. Used for non-NixOS Linux installs. The NixOS .nix definitions take precedence on rumi-vps.

6. Deploying NixOS Changes

Command

sudo nixos-rebuild switch --flake .#rumi-vps \
  --override-input private-config path:/etc/guardian-private

Dry Run

sudo nixos-rebuild dry-activate --flake .#rumi-vps \
  --override-input private-config path:/etc/guardian-private

Pitfalls

Post-Deploy Verification

systemctl status guardian-core rumi-platform rumi-server
journalctl -u guardian-core -n 20 --no-pager
journalctl -u rumi-platform -n 20 --no-pager
journalctl -u rumi-server -n 20 --no-pager

7. Elixir Development

Project: platform/

Common Commands

cd platform && mix deps.get          # Fetch dependencies
cd platform && mix compile            # Compile
cd platform && mix compile --warnings-as-errors  # Strict compile
cd platform && mix test               # Run tests
cd platform && mix phx.server         # Start dev server (port 4000, kernel disabled)
cd platform && mix format             # Format code
cd platform && mix credo              # Lint
cd platform && mix dialyzer           # Static type analysis
cd platform && mix precommit          # compile --warnings-as-errors + unlock unused + format + test

Config Hierarchy

Required Env Vars (prod)

Building a Release

cd platform && MIX_ENV=prod mix release --overwrite
# Output: platform/_build/prod/rel/guardian/bin/guardian

Mix Aliases

8. Docker Container Development

Image: guardian-core-agent

Build Pipeline (container/build.sh)

1. cd container/
2. Build @guardian/shared types (npx tsc in shared/)
3. Copy shared/dist + package.json → .shared-cache/
4. docker build -t guardian-core-agent:<tag> .

./container/build.sh          # Build with tag "latest"
./container/build.sh v1.2     # Build with custom tag

Dockerfile Layer Order

1. FROM node:22-slim
2. apt-get: Chromium + system deps + GitHub CLI (gh)
3. Install Bun 1.3.8 to /opt/bun
4. Set AGENT_BROWSER_EXECUTABLE_PATH, PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH → /usr/bin/chromium
5. bun add -g agent-browser @anthropic-ai/claude-code
6. COPY .shared-cache/ /shared/
7. COPY agent-runner/package.json + bun.lock → /app/
8. bun install
9. COPY agent-runner/ → /app/
10. bun run build (TypeScript compilation)
11. mkdir /workspace/{group,global,extra,ipc/messages,ipc/tasks}
12. Create /app/entrypoint.sh
13. chown -R node:node /workspace
14. USER node

.dockerignore

**/node_modules
**/.tsbuildinfo

Container Packages

Testing Container

# Quick test
echo '{"prompt":"What is 2+2?","groupFolder":"test","chatJid":"test@g.us","isMain":false}' | \
  docker run -i guardian-core-agent:latest

# Interactive shell
docker run --rm -it --entrypoint /bin/bash guardian-core-agent:latest

# Full test with mounts (see /debug skill for details)

Rebuilding

./container/build.sh                    # Normal rebuild
docker builder prune -af && ./container/build.sh  # Clean rebuild

9. CI Pipeline

Source: .github/workflows/ci.yml

Triggers: push to main, all pull requests.

Jobs

Nix in CI

All jobs use:

• •DeterminateSystems/nix-installer-action@main — installs Nix
• •DeterminateSystems/magic-nix-cache-action@main — caches Nix store

All commands run inside nix develop --command ... to use the pinned devShell.

What's NOT in CI

• •Elixir compilation/tests (platform/)
• •Docker image builds
• •NixOS configuration checks
• •Secret decryption

10. Project Directory Reference

Tracked in Git

Runtime (Not in Git)

Host-Only (VPS, Not in Git)

11. Troubleshooting

Nix / devShell

NixOS Deployment

Elixir / Phoenix

Docker / Container

For container-specific debugging (mounts, env vars, sessions, IPC), see the /debug skill. For deployment commands and troubleshooting, see the /self-update skill.