Release line: Alpha v.2 (in development) adds a decentralized social feed in the hub, POST /v1/social/posts, and PinIntent rows for CIDs you amplify — so desktop and phone clients using the same gateway + DID session coordinate what to keep pinned. Alpha v.1 was the savepoint: ingestion toolkit, gateway, moderation, and docs without a first-class feed — tag your tree before merging v.2 work if you need a rollback label.

alt.dream is the browser for DreamSystemz — an alternative dream to corporate centralization where IPFS, DIDs, and your nodes carry identity, media, and sync instead of a single company’s servers. The name is intentional: not escapism, but a different shape of infrastructure — legible pinning, personas, bandwidth, and “who holds what” across the apps you choose to run.

DreamSystemz is the shared story: one did:key, one gateway, one inbox — two webapps, like Facebook and Messenger:

Open the alt.dream site for social; click Messages (or visit gHosted.u directly) for chat. Same account, same gateway mailbox — different surfaces.

This repo ships the social webapp, the gateway, and the protocol. The gHosted repo builds the gHosted.u messenger webapp (plus optional Tauri/mobile shells).

This repository is the DreamSystemz browser shell and its operator stack:

• Cross-app views — pin health, storage, and usage narratives that span more than one add-on.
• Personas — DID-backed identities; one human may run several public faces with clear data boundaries.
• Per-app buckets — data grouped under an ecosystem add-on for each persona so the browser can show clean, per-bucket breakdowns.

Until there is a published npm package, ecosystem types and Zod schemas live in this repo under packages/protocol (keep in sync with gHosted when shared/ecosystemProtocol.ts exists there). They define shapes such as:

• EcosystemReferenceEvent — links a CID (or content digest) to a stable place id, surface, optional personaDid, optional ecosystemBucket.
• PinIntent — optional declaration that a user intends to pin a CID (for dashboards).
• ConversationPolicy / ParticipantMediaPolicy — local-first chat retention and media preferences.

Ingestion: the hub accepts the same JSON shape the gHosted CID map export is expected to use, merges with ingestReferenceEventsJson from @altdream/protocol, and partitions views by personaDid + ecosystemBucket.

@altdream/protocol ships the primitives that let alt.dream and gHosted speak as the same did:key without a central IdP:

• generateKeypair, publicKeyToDidKey, didKeyToPublicKey, signMessage, verifyDidKeySignature — Ed25519 + did:key.
• exportKeystore / importKeystore — passphrase-encrypted JSON keystore (AES-GCM + PBKDF2-SHA256). Carry the same keystore.json between apps.
• createChallenge / verifyChallenge, createSessionToken / verifySessionToken — the challenge → sign → JWT login flow, exposed by the gateway as POST /v1/auth/challenge + POST /v1/auth/login.
• createDpopProof / verifyDpopProof — per-request signed JWTs (DPoP-style) for app-to-app callers that don't want to manage sessions; sent as DPoP: <jwt> and verified end-to-end against the caller's did:key.

The hub's "Sign in with DID" panel runs the full flow visually: generate or import a keystore, unlock it locally, and sign in to the gateway. After that every /v1/* call goes out with the resulting bearer attached. Server-to-server callers can skip the session entirely and use DPoP. See docs/SHARED_IDENTITY.md for the wire contract gHosted should mirror.

node scripts/altdream-id.mjs generate --out my-keystore.json    # once per user
node scripts/altdream-id.mjs login http://localhost:8787 my-keystore.json
# → token: <session bearer>

• Make pin support, space, and bandwidth understandable across personas and apps.
• Stay local-first where possible; aggregate only what the user explicitly syncs or exports.
• Grow toward mesh visibility (libp2p / pinning metrics) without pretending every byte lives in one database.

Requirements: Node.js 22+ and pnpm 9 (or run commands via npx pnpm@9.15.4 … if pnpm is not global).

cp .env.example .env
# Set GATEWAY_API_KEY in .env for a serious local run. If empty, the gateway accepts Bearer `dev-insecure-change-me` only for local dev.
# Optional: SOCIAL_RL_MAX, SOCIAL_ECOSYSTEM_BUCKET for the alpha v.2 social feed API.

pnpm install
pnpm dev   # also starts gHosted.u on :5000 if not already running (see GHOSTED_ROOT in .env)

• Hub (Vite + React): http://localhost:5173 — social platform (feed, friends, profile).
• Gateway (Hono + SQLite): http://localhost:8787 — shared backend for social + messenger.
• gHosted.u (auto-started): http://localhost:5000 — messenger webapp; clone gHosted to ../gHosted/gHosted or set GHOSTED_ROOT in .env.

The hub dev server proxies /gw/* → gateway /v1/* so you can avoid CORS while testing (keep API tokens in the hub UI only; do not ship secrets in VITE_* vars).

Production builds

pnpm run build
node apps/gateway/dist/index.js
# Serve apps/hub/dist with any static host (nginx, S3, etc.).

Docker

docker compose up --build
# Optional Kubo sidecar on the same Docker network — set IPFS_API_URL=http://ipfs:5001 in .env then:
docker compose --profile ipfs up --build

System tray launcher

For day-to-day use you don't need a terminal — apps/tray is a small Electron tray app (Windows / macOS / Linux) that owns the gateway lifetime and opens the hub in your default browser. It sets HUB_DIST=apps/hub/dist so the gateway serves the built hub at / on the same port, so there is one URL to remember.

pnpm install
pnpm run tray   # builds protocol + hub + gateway, then launches the tray

Tray menu: Open Dashboard, Gateway Health, Start / Restart / Stop Gateway, Open Logs Folder (data/logs/tray-YYYY-MM-DD.log), Quit. The gateway runs as a system-Node child process so its native modules (better-sqlite3) keep the same ABI as pnpm install. See apps/tray/README.md for details.

Optional: contributor add-on (@altdream/contrib)

Voters and maintainers can install a separate small CLI (not Radicle; not part of the default hub) to sign UTF-8 payloads with the same keystore.json as the identity tools:

pnpm install
pnpm --filter @altdream/contrib build
pnpm run contrib -- help
# whoami / sign — see apps/contrib/README.md
# Or: node apps/contrib/dist/cli.js help

Design and roadmap: docs/CONTRIBUTOR_ADDON.md.

Point a local gHosted instance at this gateway for attachment offload once the client supports it — see docs/GHOSTED_MOBILE_HANDOFF.md. Living architecture notes: docs/planning.md.

Suggested environment ideas for a split deploy:

MIT. Issues and PRs are welcome for the hub, gateway, and protocol package; behavior of companion apps belongs in their own repositories.

alt.dream — an alternative dream: freedom, legibility, and your mesh.