wild-pc/AGENTS.md

AGENTS.md — Castle

You are working in the Castle repository — Paul's personal software platform, a monorepo of independent programs (services, tools, libraries, frontends) managed by the castle CLI.

What Castle does

Castle turns a source repo into something running on this node. The two halves:

• programs/ — the software catalog: what software exists (source, stack, build, system_dependencies).
• deployments/ — how a program is realized here, discriminated on its manager: systemd (a service, or a job with a schedule), caddy (a static frontend), path (a CLI on your PATH), or none (an external reference). The human-facing kind (service/job/tool/static/reference) is derived from the manager, never stored.

Using the castle CLI

It's resource-first — operations live under the resource they act on:

castle program create <name> --stack <python-cli|python-fastapi|react-vite>
castle program add <path|git-url>              # adopt an existing repo
castle service create <name> --program <p> --port <n>
castle service deploy <name> && castle service enable <name>
castle gateway reload                          # update reverse-proxy routes
castle deploy && castle start                  # apply config, then start everything
castle status                                  # unified status
castle list --json                             # all deployments, machine-readable

Expose a service on the network by setting proxy: true (→ <name>.<gateway.domain>); add public: true for the Cloudflare tunnel.

Read this first

• @CLAUDE.md — full architecture, the complete castle verb list, registry model, DNS/TLS, and code-style conventions. This is the authoritative guide.
• docs/registry.md, docs/dns-and-tls.md, and docs/stacks/*.md — deep dives.

Key principle: regular programs must never depend on castle. They take standard config (data dir, port, URLs) via env vars; only castle's own programs (CLI, gateway, api) know castle internals.

Broader context about this machine and Paul's other projects lives at /data/.lakehouse/AGENTS.md.