Self-host

The same product on your Postgres: one container, no cluster, no queue. Bring your own node, or bundle one.

Install the CLI with bun add -g @secondlayer/cli. Sizing: Hardware; Runes adds a Bitcoin node.

Ready for real traffic: your node, a pinned version, backups, upgrades. Starting out? Run it locally first with Start it.

Profiles

Set them in .env so every docker compose command picks them up:

There is no bundled Stacks-only mode: a bundled node needs Bitcoin data, and there is no public RPC default for it. Sizing for each: Hardware.

Pin a version

docker compose up runs latest. Pin a commit so a restart never changes what you run:

• Images are ghcr.io/ryanwaits/secondlayer-runtime and secondlayer-bitcoin, tagged by short commit.
• docker compose up -d --build builds your checkout instead.

Connect your node

With NODE_MODE=external, this entry in your node's Config.toml sends Secondlayer every block.

secondlayer observer --mode signer-shared --endpoint 10.0.0.5:3700 prints it.

Node on another host:

Config

Six required non-secrets, plus one compose derives for you. Secrets come from secondlayer init.

Unknown keys and contradictions fail before ingest.

Instance token

The instance token opens your box. init writes it to .env.local.

• The variable is INSTANCE_TOKEN. It is not the account key from Keys and billing.
• Never put sk-sl_* in INSTANCE_TOKEN, or the hex token in SECONDLAYER_API_KEY.

Loopback is the publish spec (API_PUBLISH_ADDR), not the caller's address. On a keyless read, a wrong key is ignored; a matching token is used.

Compose requires the token, for two reasons:

• The container process has to bind 0.0.0.0 or the published port never reaches it.
• An instance that binds past loopback with no token refuses to start.

API_PUBLISH_ADDR is how the API learns which of those two facts to serve on. It carries the publish spec:

• With the default API_PORT of 127.0.0.1:3800, the /v1 reads stay keyless.
• Changing API_PORT to 0.0.0.0:3800 makes every /v1 request carry the token.
• Writes take the token either way.

What differs on your box

Consumers running on another box: Deploy your app.

Verify and repair

Verified archive owns flags and exit codes.

Archive trust root

Every archive manifest is checked against one key before the CLI acts on it. The key comes from, in order:

1. --public-key
2. ARCHIVE_SIGNING_PUBLIC_KEY in your env
3. The key compiled into the CLI release

• It applies to bootstrap, verify and repair.
• init writes the resolved key into .env.local, so the instance verifies with no path to any Secondlayer host.
• Plaintext http:// key sources are never consulted.
• A signed latest.json pointer has to verify against the same key before its snapshot is followed.

The tradeoff: rotating the archive key means a CLI release until a key ceremony lands. To pin a different archive:

• Replace ARCHIVE_SIGNING_PUBLIC_KEY in .env.
• A value you set there survives init re-runs.

Running other teams' subgraphs

A subgraph handler is code you deploy into the instance, so it runs with the instance's trust. That is fine for your own subgraphs.

To run another team's on one box, give each team its own stack instead of sharing one:

• Its own Postgres and its own network.
• Its api and subgraph-processor containers under gVisor (runtime: runsc), as a non-root user.
• A read-only root filesystem, with bounded memory, CPU and process count.

docker/workload/tenant.compose.yml is the working shape. gVisor can't reach Docker's embedded DNS, so give each stack a static address for Postgres and a plain resolv.conf. The file explains both.

Not in the box

• Multi-tenant catalog
• A managed stack: hosted subgraphs and webhooks run on api.secondlayer.tools with an account key
• Archive publisher (separate image)
• Pay-per-call metering on your instance (the x402 rail was removed)

Support is community: github.com/ryanwaits/secondlayer.

Index every rune etch, mint, transfer and burn since block 840,000 on your own box, read through the same Runes routes as hosted. Add these lines to .env, pointing at a Bitcoin node with txindex=1:

The first sync reads every block from 840,000 and takes about half a day. tip.block_height in each response shows how far it has read. The tradeoff: Runes has no archive yet, so a new box rebuilds from your node instead of downloading, and secondlayer verify covers Stacks only.

Bitcoin node

Runes only

No Stacks node? Skip Fill it with history and connect nothing. The Stacks side still runs and stays empty; only runes reads a chain.

Upgrades with Runes

A schema migration on a full Runes database can run for hours on upgrade. The Runes tip holds still until it finishes; that is expected, not a hang.

What a self-hosted box needs, so you size it before the sync starts rather than after.

Mainnet full history is large: the reference index measures ~500 GB.

• About 250 GB is blocks, transactions, and events. The rest is the decoded plane.
• Budget roughly 3 GB per 100k blocks for core datasets, or 6 GB with a broad decoder set.
• Those are averages over history that is much denser at the tip.

Postgres

Postgres max_connections ≥ 50.

• Compose sets the Postgres cache to 1 GB (POSTGRES_SHARED_BUFFERS).
• For a full-chain sync, give it about 25% of RAM. At the stock 128 MB, inserts wait on index reads from disk and the sync runs slower.
• The bundled-node figure is dominated by the chain itself: Stacks chainstate alone measures 1.3 TB, and bitcoind is additional.

With Runes

Runes adds to the rows above:

runes keeps Runes state in memory: 7 to 12 GB while following the tip, up to 17 GB during the first sync, capped at 22 GB.

Floors enforced at start

The runtime checks RAM, disk, and max_connections at start and refuses to boot below these floors, so an undersized box finds out before it spends hours acquiring an index it cannot hold. Disk is total filesystem capacity, not free space, since a healthy instance legitimately fills most of its disk. An unmeasurable dimension is reported and skipped rather than assumed bad.

To run below a floor anyway:

That downgrades the refusal to a warning at every start. It exists so a box that was already undersized can still come back up after an upgrade: you keep the ability to run your own hardware, you just do it knowingly.

Back up first, then move to a newer release.

Backup

secondlayer backup writes one bundle: the index, plus the keys encrypted under a passphrase you supply.

A restore refuses before writing anything if the secrets key the instance will use is not the key the data was encrypted with.

A restore is all or nothing:

• pg_restore runs in one transaction and stops on the first error, so a disk that fills mid-load leaves the target as it was rather than half replaced.
• The tradeoff is no parallel restore.
• After the load the canonical block range is compared with the manifest's scope. A dump that stops short of what it promised exits 1 instead of reporting success.
• The dump digest is streamed, so a multi-gigabyte bundle hashes without being read into memory.

The bundle carries three keys:

• INSTANCE_TOKEN
• SECONDLAYER_SECRETS_KEY
• STREAMS_SIGNING_PRIVATE_KEY

Losing those costs you more than losing the index. The index can be rebuilt from the archive; the keys cannot. Store the bundle somewhere your Postgres backups are not.

Confirm any restore with secondlayer verify all --against <manifest> before trusting the result. Take a backup before you upgrade.

Upgrade

Move from the commit you run (X) to a later one (Y), keeping the database and the keys.

One jump to Y; read every changelog entry dated after X first, since that page owns what broke. The CLI is a separate npm version: bump it to match the instance you land on.

The index can be rebuilt from the archive. The keys cannot.

Losing SECONDLAYER_SECRETS_KEY makes every existing whsec_ unreadable; rotate each webhook rather than minting a new master key (signing secrets). A full dump of a mainnet index takes hours, so a filesystem snapshot of the volume is the faster backup if the host can take one.

Check out Y for its compose file, pin the same commit, then restart:

--remove-orphans stops services Y's compose file no longer lists. Migrations run at boot under an advisory lock, forward-only. Then confirm /health is ok and verify against the archive:

To roll back, pin X again. A migrated schema stays migrated, so roll back the image, not the database.