**Status:** Active — this is the current plan

The AWS serverless architecture described in [[Design/Platform_Overview]] works, but it optimizes for a problem we don't have: elastic scale and zero cost at rest. The tradeoff is complexity — VPC endpoints, Mangum adapters, DynamoDB Streams to avoid SQS endpoint costs, Lambda cold starts, EFS mount latency. All of that machinery exists to make Lambda work, not to make the wiki work.

robot.wtf is a free, volunteer-run wiki service for the ATProto community. No premium tier, no billing, no Stripe. The hosting is a Debian 12 VM on a Proxmox hypervisor with a static IP and generous RAM and disk. The deployment is conventional: persistent processes, local disk, SQLite, Caddy. The application logic — multi-tenant Otterwiki, MCP tools, semantic search, ACL enforcement — ports over from the Lambda implementation with minimal changes. The middleware we already built for Lambda is WSGI middleware with a Mangum wrapper; removing the wrapper gives us back the WSGI middleware.

The ATProto identity system replaces WorkOS as the auth provider. Users sign in with their Bluesky handle (or any ATProto PDS account). Identity is a DID — portable, user-owned, and philosophically aligned with "your wiki is a git repo you can clone." The target audience (developers and researchers using AI agents) overlaps heavily with the ATProto early-adopter community.

Debian 12 VM running on a Proxmox hypervisor. Static IP, generous RAM and disk allocation. If the VM ever needs to move, the deployment is portable to any Linux box (Hetzner, DigitalOcean, Fly.io, bare metal, or back to AWS on an EC2 instance) — nothing is host-specific.

Wildcard TLS requires a DNS challenge. Caddy supports this natively with plugins for common DNS providers (Cloudflare, Route 53, OVHcloud). The DNS zone for robot.wtf needs API credentials configured in Caddy.

The `did` is the stable identity. The `handle` is refreshed from the PDS on each login (handles can change). The `username` is the platform-local slug used in URLs — immutable after signup.

robot.wtf is an ATProto OAuth **confidential client**. The flow:

The platform JWT is signed with our own RS256 key (stored on disk). After step 10, the PDS is not in the runtime path — the platform JWT is self-contained and validated locally. ATProto tokens are stored in the session database for potential future use (e.g., posting to Bluesky on behalf of the user), but they're not needed for wiki operations.

Bluesky maintains a Python Flask OAuth demo in `bluesky-social/cookbook/python-oauth-web-app` (CC-0 licensed). It implements the full ATProto OAuth flow as a confidential client using `authlib` for PKCE, DPoP, JWK/JWT, and code challenge. This is the starting point for our auth service. It handles the hard parts: handle-to-DID resolution, PDS Authorization Server discovery, PAR, DPoP nonce management, and token refresh. See [[Dev/V3_V5_Risk_Research]] for detailed assessment.

- `authlib>=1.3` — PKCE, JWK/JWT, DPoP proof creation, code challenge

robot.wtf's MCP OAuth AS is a thin layer. It delegates authentication to ATProto (step 6) and handles authorization itself (does this user have access to this wiki?). The token it issues is a JWT containing the user's DID and the authorized wiki slug, signed with our RS256 key.

--url https://{slug}.robot.wtf/mcp \

Same approach as [[Design/Frontend]]: platform JWT stored as an `HttpOnly`, `Secure`, `SameSite=Lax` cookie on `.robot.wtf`. Every request to any subdomain includes the cookie. The Otterwiki middleware and MCP sidecar both validate JWTs using the same public key.

The SQLite database lives at `/srv/data/robot.db`. Write concurrency is handled by SQLite's WAL mode, which supports concurrent reads with serialized writes. For a wiki platform where writes are infrequent relative to reads, this is more than adequate.

Gunicorn runs with multiple workers. The Proxmox VM has generous RAM, so worker count is limited by CPU cores, not memory. Git write operations are serialized per-repo by git's own lock file.

A lightweight Flask app handling the management API (wiki CRUD, ACL management, token generation) and the Git smart HTTP protocol. This is the same API surface described in the archived [[Design/Implementation_Phases]], with SQLite queries instead of DynamoDB calls.

The Git smart HTTP endpoints (`/repo.git/info/refs`, `/repo.git/git-upload-pack`) use dulwich to serve the bare repos on disk. Read-only (upload-pack only) — users can clone and pull their wikis at any time.

The Proxmox VM has plenty of RAM, so loading MiniLM in both the MCP sidecar and a dedicated embedding worker is fine. The Otterwiki process and platform API don't need it — they just write to the reindex queue.

| SQLite database | `/srv/data/robot.db` | **High** — reconstructable from repos but painful |

**Proxmox snapshots:** The Proxmox hypervisor can take VM-level snapshots. These are a useful complement to application-level backups — a snapshot captures the entire VM state for rapid rollback after a bad deploy. Not a substitute for offsite backups (snapshots live on the same hardware).

If the VM dies completely, recovery is:

1. Provision a new VM (on Proxmox or any other host)

7. Update DNS to point to new IP (if it changed)

RTO: hours (mostly limited by repo restore transfer time). RPO: 24 hours (daily backup cycle). This is acceptable for a free community service. If tighter RPO is needed, increase backup frequency or add streaming replication to a standby.

ssh vm

sudo systemctl restart robot-otterwiki

ssh vm

1. Provision Debian 12 VM on Proxmox, assign static IP

For a volunteer-run service, keep monitoring simple:

- **Health checks:** Each service exposes a `/health` endpoint. An external monitor (UptimeRobot, free tier) pings them.

| Domain | wikibot.io | robot.wtf |

| Host environment | AWS (managed) | Debian 12 VM on Proxmox |

| Secrets | Secrets Manager | Files on disk |

1. ~~**ATProto Python OAuth library maturity.**~~ **RESOLVED.** The Bluesky Flask demo uses `authlib` (not `joserfc` — earlier research was wrong). Dependencies are `authlib>=1.3`, `dnspython`, `requests`, `requests-hardened`, `regex`. All mature. The demo is ~600 lines, well-factored, and directly adaptable. See [[Dev/V3_V5_Risk_Research]].

2. ~~**MCP OAuth AS scope.**~~ **RESOLVED.** `authlib` provides `AuthorizationServer`, `AuthorizationCodeGrant` (with PKCE), and `ClientRegistrationEndpoint` (RFC 7591). The Flask OAuth 2.0 server components handle the heavy lifting. We implement model callbacks (save_client, save_token, query_client) against SQLite. See [[Dev/V3_V5_Risk_Research]] for implementation sketch.

3. **Caddy DNS challenge provider.** Wildcard TLS requires DNS API access. Which DNS provider hosts the robot.wtf zone? Cloudflare, Route 53, and OVHcloud are all supported by Caddy. The DNS provider choice should be made before deployment.

4. **Claude.ai MCP OAuth compatibility.** The self-hosted OAuth 2.1 AS approach should work — Claude.ai's MCP client follows standard OAuth 2.1 discovery. Key finding: Claude.ai uses `client_secret_post` auth method and does NOT require DPoP. The risk is in underdocumented client quirks. Mitigation: build a minimal stub AS early and test against Claude.ai before building the full thing. See [[Dev/V3_V5_Risk_Research]].

5. ~~**ATProto scopes.**~~ **RESOLVED.** The ATProto spec explicitly says: "A client may include only the `atproto` scope if they only need account authentication." The `sub` field in the token response contains the DID. We request scope `"atproto"` and nothing else. See [[Dev/V3_V5_Risk_Research]].

6. **Docker Compose vs. systemd.** Both work. Docker Compose gives you reproducible builds, isolation, and easier migration between hosts. Systemd is lighter, native to Debian, and avoids Docker's overhead. For a Proxmox VM where we control the environment completely, systemd is probably sufficient. Docker adds value if we expect to move the deployment frequently.