PHATT-CLAW

PHATT Controlled Lightweight Agent Workflow

Container management layer for PHATT-RAID (Unraid 6.12.10) that gives AI agents controlled Docker access without handing them the raw socket and full root.

---

What This Does

Two deployment patterns on the same Unraid host:

Pattern	Purpose	Access	Image
PHATT-CLAW	HTTP API proxy for container lifecycle (list, start, stop, restart, logs)	HAProxy-filtered, network-isolated	lscr.io/linuxserver/socket-proxy
3ds-build	Docker-in-Docker ARM cross-compilation for Nintendo 3DS homebrew	Raw Docker socket (full root)	devkitpro/devkitarm + portlibs

PHATT-CLAW is for Ledger (general orchestration agent). 3ds-build is for Paperclip build agents (CEO, Lead Programmer, Senior Engineer) compiling code for project-veles.

Quick Start

# Clone
git clone https://github.com/phattbeats/phatt-claw.git
cd phatt-claw

# Copy and edit env
cp .env.example .env

# Create network + deploy proxy
docker network create phattclaw-network --driver bridge --subnet 172.19.0.0/16 --gateway 172.19.0.1
docker compose up -d

# Verify
curl http://127.0.0.1:2375/_ping

See QUICKSTART.md for the full walkthrough including 3ds-build setup.

Repo Structure

phatt-claw/
├── README.md                  # You are here
├── docker-compose.yml         # PHATT-CLAW proxy deployment
├── docker-compose.3ds.yml     # 3ds-build image build (optional)
├── .env.example               # Environment template
├── .gitignore
├── docs/
│   ├── PROJECT.md             # Architecture, rationale, terminology
│   ├── SPEC.md                # Full implementation spec
│   ├── QUICKSTART.md          # Step-by-step deployment guide
│   └── EXAMPLES.md            # curl commands + Ledger integration code
└── examples/
    ├── ledger-tool.py         # Reference Python client for Ledger
    └── build-skill.sh         # Reference build script for Paperclip agents

Security Model (Read This)

Three things protect your containers. One thing doesn't, despite appearances.

Real controls:

1. Network isolation — proxy binds to 127.0.0.1:2375, reachable only via phattclaw-network
2. HAProxy endpoint filtering — default-deny, only explicitly enabled API paths forwarded
3. Application-level label check — Ledger verifies phattclaw.managed=true before lifecycle ops (enforced in Ledger's code, NOT at the proxy)

Not a real control: 4. :ro socket mount — prevents deleting the socket file, does NOT prevent API writes through it. Unix sockets use send()/recv(), not write(). Details

Not yet implemented: 5. API key auth — planned for Phase 4 via NGINX/Caddy sidecar. Currently any container on phattclaw-network can hit the proxy without credentials.

Phases

• Phase 1 — Spec + docs (this repo)
• Phase 1 — Deploy PHATT-CLAW proxy on Unraid
• Phase 2 — Build + deploy 3ds-build image
• Phase 3 — Full loop (agent commit → build → artifact → Discord → 3dslink deploy)
• Phase 4 — NGINX auth sidecar, audit logging, label enforcement at proxy layer

Related

• project-veles — 3DS homebrew game (the thing being compiled)
• LinuxServer socket-proxy — base image for PHATT-CLAW
• devkitPro — ARM cross-compilation toolchain
• Azahar — 3DS emulator (LinuxServer Docker image available, potential addition for testing without hardware)

License

MIT