bluesky-social/indigo: Go Services and Libraries for atproto

What indigo solves for Go developers

indigo addresses the gap between atproto's protocol definitions and Go implementations. The repository description identifies it as Go source code for Bluesky's atproto services, while the README separates that work into Go services, developer tools, and reusable Go packages. The target audience is therefore not only Bluesky application developers, but also engineers who need to interact with atproto repositories, firehose data, APIs, identities, schemas, cryptographic material, or decentralized repository structures.

The service layer includes tap, described as a synchronization and backfill tool for atproto applications. Relay is a reference implementation for relaying network events. Rainbow is a firehose splitter or fan-out service, which separates event distribution from consumers that each need their own stream. Hepa is an auto-moderation bot for Ozone. These are infrastructure and protocol-oriented tools, not a general-purpose social network client.

The package layer reaches lower into the protocol. It contains generated types for `com.atproto.*` and `app.bsky.*` Lexicons, an HTTP API client, an AT OAuth client, DID and handle resolution, identifier parsing, Lexicon schema validation, repository data structures, a Merkle Search Tree implementation, and cryptographic signing and key serialization. That makes indigo relevant when an engineer needs protocol primitives rather than merely a command-line service.

How indigo models atproto data

The repository layout separates protocol implementation from higher-level commands and operational components. The `atproto/` tree contains the reusable protocol packages, including `atclient`, `auth/oauth`, `identity`, `syntax`, `lexicon`, `repo`, `repo/mst`, and `atcrypto`. The `api/atproto` and `api/bsky` trees hold generated Go types for the corresponding Lexicon namespaces.

This separation gives a Go program several possible boundaries. An HTTP-facing component can use `atproto/atclient`, while identity-related logic can work with `atproto/identity`. Code that receives structured records can validate or generate types through the Lexicon-related packages. Repository code can use `atproto/repo` and its Merkle Search Tree implementation, and signing code can use `atproto/atcrypto` for cryptographic operations.

The commands layer sits above those packages. The README identifies `cmd/tap`, `cmd/relay`, `cmd/rainbow`, and `cmd/hepa` as the principal Go services. The repository also contains operational directories such as `events/`, `backfill/`, `carstore/`, `repomgr/`, and `splitter/`, indicating that event ingestion, storage, repository management, and stream distribution are treated as distinct concerns. The exact runtime data flow of each command is delegated to its own README rather than documented in the top-level README.

One important boundary is that indigo is not the TypeScript reference implementation. The README directs readers to `bluesky-social/atproto` for the TypeScript reference implementation, including PDS and bsky AppView services, and to `bluesky-social/social-app` for the Bluesky client. Indigo is the Go-side collection, not a replacement for every Bluesky component.

Installing indigo and building its commands

The README gives a short path for installing a command with Go. It assumes that Homebrew is available for installing Go on systems where that is the chosen setup. The example installs `tap` from the repository module path and then invokes the installed command. Go fetches dependencies, compiles the package, and places the executable in the Go installation's command path.

Install Go with Homebrew as shown in the README:

brew install go

Then install the tap command from the repository module:

go install github.com/bluesky-social/indigo/cmd/tap
tap

The first command installs Go itself. The second block installs `tap` and starts it. If the executable is not found after installation, the README does not document a separate PATH setup procedure, so that environment issue must be checked against the local Go installation rather than inferred from this repository.

For source development, the README says to use the Makefile. The listed wrapper commands build or test the repository, format code, and run lint checks. These commands operate on the checked-out repository rather than installing individual tools globally:

make build
make test
make fmt
make lint

`make build` builds the service executables listed in the Makefile, including relay, beemo, lexgen, stress, fakermaker, hepa, sonar, and tap. `make test` runs the Go test suite. `make fmt` modifies files in place, while `make lint` runs `go vet` and checks that `gofmt` reports no unformatted files.

For a direct development invocation, the README gives this command:

go run ./cmd/relay

This starts the relay command from the current checkout. The README does not provide a complete relay deployment configuration, database setup, or production startup sequence, so `go run ./cmd/relay` is a development entry point rather than a full installation guide.

Tap, relay, rainbow, and hepa have different jobs

Choosing an indigo service requires matching the command to the data operation. Tap is the clearest fit for synchronization and backfill, as stated in the README. It is aimed at atproto applications that need to populate or update local state from network data. The top-level documentation does not expose Tap's storage schema, cursor configuration, or recovery procedure, so those details should be obtained from `./cmd/tap/README.md` before deployment.

Relay has a different scope. It is described as a relay reference implementation, which makes it useful when examining how a relay is organized or when building a service that needs relay behavior. The repository does not present it as the Bluesky AppView, and it should not be confused with the PDS or bsky AppView implementation in the TypeScript repository. A team looking for those services must use the repository named by the README.

Rainbow is explicitly a firehose splitter or fan-out service. That distinction matters when a workload needs to distribute one event stream to multiple consumers. Tap and Rainbow should not be treated as interchangeable. Tap is described as synchronization and backfill, while Rainbow is described in terms of stream separation and fan-out.

Hepa is an auto-moderation bot for Ozone, so it is relevant to moderation workflows rather than general repository synchronization. The README links Ozone as the associated system but does not document Hepa's configuration, event inputs, or operational behavior. Its dedicated README is the appropriate source for those details.

The package API is explicitly unstable

The largest adoption risk is stated directly in the README: all packages in the repository are under active development, and features and software interfaces have not stabilized and may break or be removed. This warning applies even though the repository is not archived and its last push was on 2026-10-13. Recent repository activity does not imply a stable package contract.

That limitation is especially relevant for teams building a long-lived service on top of `api/atproto`, `api/bsky`, or the `atproto` packages. The generated Lexicon types may track protocol changes, and the README does not promise compatibility across unreleased revisions. It also documents no GitHub releases, so there is no release-based adoption signal documented in the repository summary. Consumers who need pinned versions should inspect `go.mod`, `CHANGELOG.md`, and the relevant package documentation before depending on an interface.

The dependency surface is also substantial. `go.mod` lists packages for storage and data structures, including Pebble, Redis, Cassandra, CAR and IPLD handling, cryptography, HTTP, Echo, Prometheus metrics, and testing utilities. That does not mean every command uses every dependency, but it shows that indigo is a broad Go service repository rather than a small standalone library. Teams should inspect the imports and deployment requirements of the specific command or package they intend to use.

The Apache-2.0 license is identified as the repository license, and the repository also contains `LICENSE-APACHE`, `LICENSE-DUAL`, and `LICENSE-MIT`. The project-specific licence terms should be reviewed for the exact files and distribution model being used. This is a repository fact, not legal advice.

When indigo is the wrong abstraction

indigo is the wrong choice when the requirement is to run the complete Bluesky application stack through one repository. The README locates the PDS and bsky AppView services in `bluesky-social/atproto`, and the web and mobile client in `bluesky-social/social-app`. Indigo's listed services are relay, synchronization, stream distribution, and moderation components, so they do not cover the full client or application stack.

It is also a poor fit for a team that does not want to work in Go or accept unstable interfaces. The repository is written primarily in Go, and its package warning explicitly anticipates breaking changes. A team that needs a stable product SDK, a complete AppView, or a user-facing social application should use the repository that owns that component instead.

The alternative is therefore architectural rather than a single drop-in replacement. Use `bluesky-social/atproto` when the requirement is the TypeScript protocol and service implementation, including PDS or bsky AppView behavior. Use `indigo` when the requirement is Go code for relay operations, atproto synchronization, firehose fan-out, Ozone moderation, Lexicon types, identity handling, repositories, or cryptographic operations. The distinction prevents a common mistake: choosing a protocol library because it exposes atproto APIs when the actual need is an application service.

Editorial conclusion

Go developers working on atproto synchronization, relays, moderation, repository structures, or protocol integration should inspect indigo, while teams needing stable application interfaces or a complete Bluesky user interface should first confirm compatibility with the changing packages. The first verification should be whether the required service or package matches the current repository and whether its deployment dependencies are documented for the intended use.

Frequently asked questions

Official sources

1. bluesky-social/indigo on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README