Skip to content
Colibri Social Documentation

Overview

This section is the practical counterpart to the architecture pages: how to get Colibri running on your own machine and what to expect once it is. If you want to run an instance for other people rather than hack on one, read Self-Hosting instead.

What you’re going to run

Section titled “What you’re going to run”

Colibri is split across two repositories, and local development normally involves both:

Repository Contains Runs as
colibri-social/api The AppView, a Node 24 and TypeScript pnpm workspace, and the compose files for its dependencies pnpm dev on 127.0.0.1:3000
colibri-social/colibri.social The client library, the website that hosts it, the native shell, and this documentation pnpm dev:client on 127.0.0.1:4321

The AppView needs no service running alongside it by default: it stores its data in a libSQL file and syncs member repos directly from their PDS rather than reading a firehose. Two pieces are optional on top of that:

  • Postgres, if you’d rather develop against the same dialect a production deployment is more likely to run. An overlay swaps the driver, see AppView development.
  • A PDS, which hosts the repository of every community and member you create, plus a small private PLC directory so the DIDs it mints stay local. Both come from an overlay in the AppView repository, see Running a PDS.

Your own account is not part of the local stack. You log in with a real Atmosphere account on a real PDS (bsky.social or wherever your account lives), and only community and message data live on the PDS you configure.

Prerequisites

Section titled “Prerequisites”
  • Node.js >=24.13.0 (.node-version pins 24.13.1) and pnpm 10.33.3: run corepack enable and the right pnpm is used for you.
  • Docker and Docker Compose, for Postgres and the local PDS overlays.
  • An Atmosphere account. If the client’s early-access allowlist is switched on, your DID has to be in it (see Client development).

The short path

Section titled “The short path”

  1. Start the AppView:

    Terminal window
    git clone https://github.com/colibri-social/api.git
    cd appview
    pnpm install
    cp .env.example .env
    # fill in .env, then, with a local PDS:
    docker compose -f docker-compose.yml -f docker-compose.pds.yml up -d

    The AppView refuses to boot without APPVIEW_DID, PUBLIC_URL, SIGNING_KEY, CREDENTIAL_ENCRYPTION_KEY, PDS_URL and COMMUNITY_HANDLE_DOMAIN filled in. See AppView development for what each does.

  2. In a second checkout, start the client:

    Terminal window
    git clone https://github.com/colibri-social/colibri.social.git
    cd colibri.social
    pnpm install
    cp .env.example .env
    pnpm dev:client

  3. Open http://127.0.0.1:4321 (not localhost, see below) and log in with your Atmosphere account.

That gives you a working client against a local AppView, communities included. Running a PDS explains how the local PDS overlay works and where its limits are.

Dev mode is not production

Section titled “Dev mode is not production”

The client takes several shortcuts when Vite is in dev mode. They change how requests flow, and they hide a few classes of bug until you build for production:

  • Requests bypass your PDS. In production every XRPC call is proxied through the user’s PDS with an atproto-proxy header, and the PDS mints the service-auth token. In dev the client calls http://127.0.0.1:3000/xrpc/... directly and mints the service-auth token itself with com.atproto.server.getServiceAuth. Proxy-only breakage therefore doesn’t show up locally.
  • The AppView origin is pinned. getAppViewHost() returns 127.0.0.1:3000 whenever import.meta.env.DEV is set, so the AppView switcher in settings has no effect locally and the AppView has to listen on that port.
  • The OAuth client is a localhost client. Per the AT Protocol localhost client rules, the client id is http://localhost?... with a redirect_uri of http://127.0.0.1:<port>/app/login. That redirect URI is why you must browse to 127.0.0.1, not localhost.
  • Early access is enforced the same way. The allowlist in packages/client/src/atproto/allowlist.ts is compiled into the client, and dev mode gets no exemption from it.

Where to go next

Section titled “Where to go next”
AppView developmentRunning the AppView, its configuration, and its Docker overlays.
Client developmentThe SolidJS client, the Astro website, and the native shell.
Running a PDSThe PDS communities live on, and how to run one locally.
ContributingChangesets, reviews, and how to get your work merged.