Iris the Goodest Girl
- Go 93.8%
- JavaScript 4.2%
- HTML 0.9%
- CSS 0.8%
- Dockerfile 0.2%
|
|
||
|---|---|---|
| .forgejo/workflows | ||
| .githooks | ||
| cmd/iris | ||
| config | ||
| docs | ||
| internal | ||
| .env.example | ||
| .gitignore | ||
| compose.yaml | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| many | ||
| README.md | ||
Iris
A self-hosted agent platform: one Go binary, many surfaces, local-first —
daily driver for the household (briefings, inbox watch, notes) and lab bench
for pushing on how agents work. We own the agent loop.
Design and decisions: docs/ARCHITECTURE.md.
Rules
- Local first. Everything runs here (OrbStack containers, UTM VMs) before it ships to the Servarica VPS. Same compose files, same config, new host.
- No scheduled jobs on the Mac. Local runs are manual (
compose up, explicit test commands). Cron/systemd timers live on the VPS only. - Clean / dirty. This repo builds the clean box. Exploit-adjacent work runs in disposable sandboxes (boxd tier), never here.
- Secrets in
.env(gitignored) or host sops-nix — never committed.
Prerequisites (Mac)
- OrbStack (Docker backend) —
docker infoshould report OrbStack. - UTM — NixOS aarch64 VM for host-parity testing (systemd timers, Tailscale).
- OpenCode with the Go Plus key (separate key per host; Extra Usage off).
Development
- CI (Forgejo Actions) runs build, vet, gofmt and the unit suite on every
push to
mainand every PR. - Local gate:
git config core.hooksPath .githooksonce per clone — the pre-push hook runs the same checks before anything leaves your machine.
Quickstart
cp .env.example .env # then fill in secrets
docker compose up -d
Layout
cmd/iris/ # the Go binary (P0 — skeleton not yet built)
docs/ # ARCHITECTURE.md — decisions, build order, open questions
compose.yaml # local stack (conduit today; mirrored on the VPS later)
.env.example # secrets template; real .env never committed
config/ # service configs (conduit, MCP profiles)
hosts/ # NixOS host declaration for the VPS (comes with provisioning)
Services
| Service | What | Local port |
|---|---|---|
| phoenix | trace UI + OTLP collector (loopback, auth on: .env) |
6006, 4317 |
| postgres | prod-profile session store; pgvector enabled for the future retrieval lab | 5432 |
| conduit | Matrix homeserver — dormant surface (adapter kept, thin and deletable); registration closed, federation off | 6167 |
The web adapter (served by iris serve on 7700, loopback; tailnet HTTPS
via tailscale serve) is the primary phone surface — an installable PWA.
Reach the homeserver over the tailnet at
https://<host>.tailnet.ts.net if the Matrix surface is reactivated.