Exosphere is a set of small, modular, self-hostable community tools built on the AT Protocol.
app.exosphere.site
1# Context
2
3Small groups of people and communities must rely on centralized and big tech tools to organize themselves or communicate.
4
5There should be alternatives where communities can self host their platforms and own their data.
6With full independence and no dependency on big tech.
7
8Some tools exist (forums or small centralized platforms), but they often add friction.
9
10We believe that AT Protocol can solve many of these issues.
11
12# Exosphere
13
14Exosphere is a set of small and modular tools.
15
16## Principle
17
18- AT Protocol Authentication
19- Public spheres are publicly readable, all interactions require an AT Protocol account
20- Data belongs to the users (stored on their PDS)
21- Self hostable
22
23## What kind of tools
24
25- Feature requests
26- Kanban board
27- Feed and discussions
28- Micro blogging
29- Forums
30- Polls
31- Event organization
32- Forms
33
34# Spheres
35
36A Sphere is a community, a small group of friends, a family, a company, whatever.
37It can be self hosted, or rely on a Sphere hosting provider.
38
39A Sphere can be public or private.
40
41## Private Spheres
42
43Private Spheres are invitation only, users must have an AT Protocol DID.
44All content is stored on the Sphere database to preserve privacy (AT Protocol repos are public by design).
45
46## Public Spheres
47
48Public Spheres content is readable by anyone. All interactions require AT Protocol authentication.
49
50### Write access modes
51
52- **Open** - Any authenticated user can participate (react, comment, post).
53- **Members only** - Public read, but only invited members can participate. Anyone can view the content, but interactions (reactions, comments) are restricted to approved members. Enforced at the AppView/indexer level.
54
55### Future: unauthenticated access
56
57Unauthenticated write access (e.g. anonymous poll votes) may be added later as an opt-in feature for specific modules. See [ARCHITECTURE.md](./ARCHITECTURE.md) for details on the tradeoffs.
58
59# Technical implementation
60
61We want the look and feel of Exosphere to be friendly but professional.
62Everything must be super reliable and fast from the ground up.
63
64- Bun
65- AT Protocol
66- TypeScript
67 - Strong types everywhere
68 - Zod schemas where needed
69- Backend: Hono.js
70- Frontend: Preact
71 - Preact Signals for state management
72 - CSS / Design systems : vanilla-extract
73
74# Getting started
75
76## Prerequisites
77
78- [Bun](https://bun.sh)
79- [Docker](https://www.docker.com/) (for the local PDS)
80
81## Setup
82
83```bash
84bun install
85
86# Generate the OAuth private key (one-time)
87bun run packages/core/scripts/generate-key.ts
88```
89
90Copy `.env.example` to `.env` and fill in the generated `OAUTH_PRIVATE_KEY`.
91
92## Local PDS
93
94A local PDS (Personal Data Server) lets you develop against AT Protocol without hitting production infrastructure.
95
96```bash
97# Generate PDS config (one-time, creates pds/pds.env)
98bun run pds:init
99
100# Start the PDS container
101bun run pds:up
102
103# Create test accounts
104bun run pds:account alice
105bun run pds:account bob
106```
107
108Each account is created with a handle like `alice.pds.dev` and a DID registered on `plc.directory`. The PDS runs at http://localhost:2583.
109
110**Login with the DID**, not the handle. Local PDS handles (e.g. `alice.pds.dev`) don't resolve via DNS. The DID (`did:plc:...`) is printed when the account is created.
111
112Other PDS commands:
113
114| Command | Description |
115| ------------------ | ------------------------- |
116| `bun run pds:logs` | Follow PDS container logs |
117| `bun run pds:down` | Stop the PDS container |
118
119## Run
120
121```bash
122# Start both backend (port 3000) and frontend (port 5173)
123bun run dev
124
125# Or start them separately
126bun run dev:server
127bun run dev:client
128```
129
130Open http://localhost:5173 in your browser. The Vite dev server proxies `/api` requests to the backend.