1# tiny23`tiny` is a self-hosted, multitenant Nostr relay. Each tenant has durable local storage, an owner, relay policy, inbox and outbox delivery, hosted sites, file storage, and optional repository browsing.45```mermaid6flowchart LR7 people((people)) -- "NIP-07 or Nostr Connect" --> ui[web pages]8 agents((agents)) -- "MCP, Buzz, GRASP" --> api[/mcp, /events, git/]9 ui --> tenant10 api --> tenant11 subgraph tenant [one tenant]12 policy[owner and policy] --> store[(durable store)]13 store --> rooms[chat rooms]14 store --> wiki[wiki]15 store --> repos[repositories]16 store --> files[files and sites]17 store --> views[views and records]18 end19 tenant -- "inbox and outbox" --> relays((other relays))20```2122## Components2324The repository contains four executables in one Go module:2526| Component | Build target | Role |27| --- | --- | --- |28| [`tinyrelay`](tinyrelay/README.md) | `make build-tinyrelay` | Standalone Nostr relay for arbitrary clients. |29| `tiny` | `make build-tiny` | Combined host with the relay, Git hosting and browser interface. |30| [`tinygit`](tinygit/README.md) | `make build-tinygit` | Standalone public Git host using signed repository metadata and refs. |31| [`tinyclient`](tinyclient/README.md) | `make build-tinyclient` | Standalone frontend connected to the combined `tiny` backend. |3233`make build` writes all four binaries to `bin/`. Go builds embed the checked-in browser assets and do not require Node.js. The integrated `tiny` command, wire formats and existing tenant data remain compatible. Standalone components have narrower capabilities: tinygit does not start a relay or private-repository service, tinyclient needs a backend and tinyrelay serves the Nostr protocol without the web UI or Git services.3435Reusable `protocol/nostr` and `protocol/auth` packages supply wire values and proof verification without importing host services. Feature semantics and access policy remain separate. See [Architecture](docs/architecture.md), [Module boundaries and protocol contracts](docs/module-contracts.md) and the [extension catalog](docs/extensions/README.md) for ownership, supported profiles and remaining seams.3637## Run locally3839Build and start the daemon:4041```sh42go build -o tiny ./cmd/tiny43./tiny serve --data-dir ./data --listen :744744```4546Run only the standalone relay:4748```sh49go build -o bin/tinyrelay ./cmd/tinyrelay50./bin/tinyrelay --data-dir ./relay-data --listen :7447 \51 --public-url wss://relay.example52```5354The standalone relay accepts ordinary Nostr clients over WebSocket. `tiny relay` runs the same standalone server through the combined CLI.5556For a public deployment, set the relay URL and provision the owner key:5758```sh59./tiny serve --data-dir /var/lib/tiny --listen 127.0.0.1:7447 \60 --public-url https://relay.example \61 --provision-owner <64-lowercase-hex-pubkey>62```6364The command is `tiny`. Useful commands include:6566```text67tiny serve [--data-dir PATH] [--listen :7447]68tiny relay [options]69tiny tenant create --name NAME --owner PUBKEY [--template default] [--source wss://...]70tiny tenant list|enable|disable|host [options]71tiny git-token --repo URL [--key-env TINY_AGENT_KEY] [--format header|value|git]72tiny templates73tiny version74```7576Create a permanent tenant with a template:7778```sh79tiny tenant create --data-dir /var/lib/tiny \80 --name community --owner <64-lowercase-hex-pubkey> \81 --template chat82```8384Run `tiny templates` to see available templates. Templates that read from an upstream relay accept `--source wss://relay.example`.8586## Configure and operate8788The web interface uses plain HTML pages and forms. Connect a Nostr signer with NIP-07 or Nostr Connect to sign in and authorize management actions. **Chat** combines group rooms with one-to-one conversations. **Account** keeps the current key's profile, relay lists and Chat presence preference together. Use the management pages to configure policy, members, relay connections, delivery jobs, backups, hosted sites, and stored files. Delivery and retry status lives under **Manage > Sync**.8990The browsing pages provide repository lists, source files, branches, history, diffs, file previews, raw downloads, synchronization status, and storage status. Access follows the tenant's current permissions.9192See [Files and private repositories](docs/files-and-private-repositories.md) for encrypted folders, resumable uploads, storage allowances, private Git hosting and Blossom draft support.9394See [Git collaboration](docs/git-collaboration.md) for issues, pull requests, conversation synchronization and participant outboxes.9596See [Membership](docs/membership.md) for invites, joining with NIP-43 and reviewing access requests.9798See [Chat](docs/chat.md) for group rooms and one-to-one conversations, open and members-only access, room administration, NIP-17 direct messages, connecting Buzz-compatible clients and agents, and the live room stream.99100See [Social](docs/social.md) for notes, long-form articles, NIP-10 and NIP-22 conversations, reactions, Markdown, media and mixed feeds.101102See [Installed app](docs/app.md) for installing the relay as an app, sharing files to it, opening Nostr links and device notifications.103104See [Agent identities](docs/agents.md) for granting an assistant or bot its own scoped key, what the relay enforces and how to pause or revoke it.105106See [Wiki](docs/wiki.md) for pages, versions and forks, merge requests and redirects.107108See [Custom views](docs/views.md) for rendering fenced code blocks through a transform you run and keeping the result as signed artifacts.109110**Manage > Health** shows the relay and script versions and whether the browser's WebMCP tools are registered. See [WebMCP tools](docs/webmcp.md) for browser-agent integration and authorization behavior.111112Agents outside the browser connect to `/mcp`, a stateless Model Context Protocol endpoint authenticated with NIP-98, and read `/llms.txt` for a summary of the relay's machine surface. See [MCP](docs/mcp.md). An agent acts under a grant the owner signs, and the owner reviews what it proposes:113114```mermaid115sequenceDiagram116 participant O as owner117 participant R as relay118 participant A as agent119 O->>R: sign a kind 30392 grant (rooms, repos, wiki, sites, kinds)120 A->>R: publish under its own key121 R-->>A: accepted, or restricted with the reason122 R-->>O: wake a device: proposal or request123 O->>R: react + or - on the exact event124 R-->>A: visible to everyone, or held125```126127## Deployment128129Build the container image:130131```sh132docker build --target runtime -t tiny:local .133docker run --rm -p 7447:7447 -v tiny-data:/data \134 tiny:local serve --listen :7447 --public-url https://relay.example135```136137For systemd, install [`deploy/tiny.service`](deploy/tiny.service), create `/etc/tiny/tiny.env`, then run:138139```sh140sudo systemctl daemon-reload141sudo systemctl enable --now tiny142```143144Keep the data directory on local durable storage. The process exposes `/healthz` and `/readyz`. An optional diagnostics listener provides `/metrics` and protected pprof endpoints. Set `--otlp-endpoint` or `OTEL_EXPORTER_OTLP_ENDPOINT` when exporting traces.145146The reference installation keeps the relay off the public interface and lets two sidecars front it:147148```mermaid149flowchart LR150 internet((internet)) --> https[https sidecar]151 tailnet((tailnet)) --> ts[tailscale sidecar]152 https --> tiny[tiny]153 ts --> tiny154 tiny --> data[(data directory)]155```156157See [Personal relay deployment](docs/personal-relay.md) for the reference installation.158159## Explore the code160161Start with [`cmd/tiny`](cmd/tiny/doc.go) for commands and process lifetime, or [`daemon`](internal/daemon/doc.go) for tenant assembly and event flow. Each internal package has a `doc.go` overview. Comments on interfaces, constructors and transaction hooks explain ownership, inputs and failure behavior where those contracts are declared. Tests live beside the code they exercise.162163Use editor symbol help or read the same comments from the command line:164165```sh166go doc ./internal/daemon167go doc ./internal/storage SaveOptions168go doc ./internal/work Handler169```170171See [Architecture](docs/architecture.md) for the package map, event acceptance and dependency checks.172173## Test and diagnose174175```sh176make test177make test-race178make docker-test179make benchmark180```181182Run the Linux race suite on a Docker host with `LINUX_HOST=<host> ./scripts/test-linux.sh`. Run the conformance harness against a started daemon with `node scripts/conformance/run.mjs`; results are written under `artifacts/conformance/`.