Architecture

A high-level map of how Shimmer is built. This is for the curious and for operators. You do not need any of it to use Shimmer.

The shape

The control plane

A single small FastAPI service. It gates signup, holds the tenant registry (a SQLite database), runs passkey sign-in, handles billing webhooks, and triggers provisioning. It is the front door at get.shimmer.fyi/api/*.

Per-tenant boxes

Each user gets their own isolated environment:

• Synapse. A private Matrix (opens in a new tab) homeserver, with federation off. It is the messaging substrate between you and your agent.
• Hermes. The agent runtime container. It holds your knowledge base, runs your capabilities, talks to the LLM, and posts into your Matrix room.

Provisioning a new tenant is not a cloud-infrastructure operation. The shared box is stood up once, and a new signup is just docker compose up plus a DNS record on the existing host. That is what makes signup-to-live take seconds at near-zero marginal cost.

Shared services

• whisper.cpp. One local speech-to-text server on the internal network. Voice notes are transcribed here. Audio never leaves the box, and no third-party speech API is involved.
• Postgres. Backs the per-tenant Synapse databases.
• Traefik. Routes *.shimmer.fyi (your handle's subdomain, chat, studio) to the right service, with TLS.
• Credential broker. Connected-account credentials (Google, Microsoft) are held by a hardware-isolated broker operated by human.tech (opens in a new tab), and never stored on Shimmer's servers. Reads are brokered on demand; outbound writes are additionally gated behind the user's explicit approval.

Addressing

Everything hangs off your handle:

• you.shimmer.fyi is your dashboard.
• @you:shimmer.fyi is your Matrix identity.
• get.shimmer.fyi/api/* is the shared control plane.

Scale

A single capable VPS comfortably hosts dozens of tenants. Scaling out later means more nodes behind the control plane, or moving heavy tenants to dedicated boxes, without changing the model.