Hubble

name: "hubble"

description: "Use Hubble, Microcosm's whole-Atmosphere public data mirror, to inspect repository coverage and status or download current repository snapshots. Use when you need a read-only, network-wide fallback for atproto sync data, repository archives, or synchronization diagnostics."

metadata:

createdAt: "2026-09-11T15:59:52.665230+00:00"

repoUrl: "https://skillz.supply/skills/did:plc:xbtmt2zjwlrfegqvch7fboei/protopack.hubble/SKILL.md"

# hubble — whole-network repository mirror

Hubble is a public, read-only mirror of AT Protocol repositories. It subscribes to
`bsky.network`, backfills repositories through `hubble-sync`, and serves the
current synchronized state even when a repository's PDS is unavailable.

- **main instance:** https://hubble.microcosm.blue
- **live API docs:** https://hubble.microcosm.blue (the root is a small health/size message)
- **source:** https://tangled.org/microcosm.blue/hubble
- **source snapshot reviewed:** `d984a19c44d31f8e4f639dc99e910b19e39ac78e`
- **dashboard:** https://microcosm.tngl.io/hubble/

This is not a historical archive. Hubble intentionally prioritizes current
availability, account deactivation/deletion handling, and a point-in-time-ish
whole-network snapshot. `getRepo`'s `since` parameter is ignored.

## choose hubble vs other services

- **hubble:** current full-repository exports and network-wide sync status
- **slingshot:** individual current records and identity resolution
- **pdsx:** authenticated record CRUD and writes
- **constellation:** backlinks and engagement queries
- **lightrail:** filtered/current-record indexes when a full repo export is wasteful

Do not use Hubble as a write target. Do not infer that an account is currently
hosted merely because it appears in `listRepos`; check its status and Hubble's
repo info when that distinction matters.

## standard sync endpoints

All examples use:

```bash
HUBBLE=https://hubble.microcosm.blue
```

**Check repository status:**

```bash
curl "$HUBBLE/xrpc/com.atproto.sync.getRepoStatus?did=did:plc:z72i7hdynmk6r22z27h6tvur"
# {"did":"did:plc:...","rev":"3ms...","active":true}
```

**Enumerate mirrored repositories:**

```bash
curl "$HUBBLE/xrpc/com.atproto.sync.listRepos?limit=1000"
```

The response has `repos` and a DID cursor. The practical limit is 1,000;
continue with `?cursor=...`. Each entry has `did`, the latest `rev`, `active`,
and a compatibility `head` field that is currently an empty string rather than
an archive CID.

**Download the current repository:**

```bash
curl -L \
  -H 'Accept: application/vnd.ipld.car' \
  "$HUBBLE/xrpc/com.atproto.sync.getRepo?did=did:plc:z72i7hdynmk6r22z27h6tvur" \
  -o repo.car
```

`getRepo` returns a stream-ordered CAR. It accepts the standard `did` and
optional `since` parameters, but `since` is unsupported and dropped: the
response is the current complete export. Hubble returns `RepoNotFound` when the
DID is unknown or not synchronized yet, and status-specific errors for inactive
repositories.

## archive formats and compression

Hubble supports two archive formats:

- `application/vnd.ipld.car` — standard CAR, the default
- `application/x.microcosm.star-lite` — compact STAR-lite export

Negotiate with `Accept`:

```bash
curl -L \
  -H 'Accept: application/x.microcosm.star-lite' \
  "$HUBBLE/xrpc/com.atproto.sync.getRepo?did=did:plc:..." \
  -o repo.star-lite
```

For simple browser links or clients that cannot set headers, Hubble also accepts
`?accept=car` or `?accept=star-lite`; that query parameter overrides the header.
The response includes `Content-Disposition` with a DID-and-revision filename.

Compression is negotiated independently through `Accept-Encoding`:

```bash
curl --compressed -L \
  -H 'Accept: application/vnd.ipld.car' \
  "$HUBBLE/xrpc/com.atproto.sync.getRepo?did=did:plc:..." \
  -o repo.car
```

STAR-lite is a Microcosm format and needs its format implementation to decode;
use CAR when interoperability with ordinary atproto tooling is more important.

## Hubble-specific diagnostics

**Global instance statistics:**

```bash
curl "$HUBBLE/xrpc/blue.microcosm.hubble.getStats"
```

The response reports total `records`, repository counts by account status and
sync state, and the configured `upstream`. Treat these as an operational
snapshot, not an immutable network denominator. In particular,
`reposBySyncState.desynchronized` means Hubble has a repo whose live state needs
resynchronization; it does not mean the repo is absent.

**Detailed repository info:**

```bash
curl "$HUBBLE/xrpc/blue.microcosm.hubble.getRepoInfo?did=did:plc:..."
```

This combines:

- `accountStatus`: effective activity, local moderation, and upstream status
- `archive`: whether a current export is available, formats, and record count
- `syncState`: state, revision, and desynchronization reason/retry time
- `history`: commits, resyncs, PDS changes, and last resync details
- `pds`: Hubble's observed PDS host
- `unverifiedHandle`: the last handle observed during identity resolution

The useful distinction is `archive.available` versus a merely known repo. A repo
can be known but pending its first sync or currently desynchronized.

**Observed upstream account-status history:**

```bash
curl "$HUBBLE/xrpc/blue.microcosm.hubble.getAccountStatusLog?did=did:plc:...&limit=100"
```

The endpoint returns `events` with timestamps, status, upstream host, and
upstream sequence. Follow its returned `cursor` for older pages. `limit` is
1–100 and defaults to 50.

## operational caveats

- Hubble mirrors the upstream's view plus its own synchronization state; it is
  not automatically the same thing as a deep crawl of every PDS.
- Large or newly discovered repositories can be `active` but unavailable until
  their first resync completes.
- A Hubble revision is an atproto TID revision, not a CAR CID or a cursor for
  incremental `getRepo` downloads.
- Hubble's `listRepos.head` is not usable as a CAR head; it is a compatibility
  placeholder.
- Prefer the custom `getRepoInfo` endpoint when diagnosing availability,
  freshness, moderation, or desynchronization instead of combining several
  standard endpoints and guessing.
- Confirm current behavior against the live instance and source: Hubble is an
  active project and its public lexicons/endpoints may evolve.