Run a Signer

How to Use This Guide

This guide is a step-by-step walkthrough for setting up and running a signer. It covers only the signer infrastructure: the signer software and the Stacks node it connects to.

If you are not familiar with the concept of signing, be sure to check out the Stackers and Signing concept guide.

Background and High-Level Process

To run a signer you'll run a signer and a Stacks node side-by-side. Specifically, run a follower node. The signer monitors events from the Stacks node and uses the generated account (see Preflight Setup) to sign incoming Stacks blocks sent from the Stacks node.

This doc provides instructions to set up both using either Docker or the release binaries available in the stacks core releases repository, and how to configure them so the signer and Stacks node communicate correctly.

Knowledge Prerequisites

• Docker and basic knowledge of pulling and running images

• Basic knowledge of Stacks accounts

1

Signer Checklist: Pre-Launch Setup

Quick reference of major setup steps prior to launching a signer.

• Ensure your system meets the minimum system requirements.

• Acquire Docker and basic knowledge of Stacks accounts (links above).

2

Signer Checklist: Preflight Setup

• Generate a new private key using stacks-cli (see Preflight Setup).

• Save the generated account information securely.

3

Signer Checklist: Configuration Setup

• Create a signer-config.toml file with necessary configurations:

  • node_host

  • endpoint

  • network

  • db_path

  • auth_password

  • stacks_private_key

• Store signer-config.toml securely and note down the values used.

4

Signer Checklist: Running the Signer

• Decide whether to run the signer using Docker (recommended) or as a binary.

• If using Docker:

  • Set up the necessary ports and volumes.

  • Run the Docker container with the appropriate settings.

• If running as a binary:

  • Build stacks-core from source or download the pre-built binary.

  • Run the signer using: stacks-signer run --config <path_to_config>.

5

Signer Checklist: Verify Signer Operation

• Check that the signer is listening on its configured endpoint.

• Confirm that there are no errors and that the system is ready for connections.

6

Signer Checklist: Setting Up the Stacks Node

• Create a node-config.toml, include:

  • connection_options.sauth_token

  • events_observer.endpoint (matching signer config)

• Decide whether to run the Stacks node using Docker or as a binary and follow the respective run steps.

7

Signer Checklist: Verify Stacks Node Operation

• Check Stacks node logs for successful connection to the signer.

• Confirm the node is syncing Bitcoin headers properly.

Minimum System Requirements

These are the minimum required specs to run a node and signer. More resources are recommended for optimal performance.

Signer, Stacks node and Bitcoin node

• 4 vCPU

• 8 GB memory if running only a Stacks node and signer

• 16 GB memory if running Stacks + Bitcoin node + signer

• 1.5+ TB storage (1 TB for Bitcoin node, 500 GB for Stacks node, and 50 GB for signer)

---

Preflight Setup

Before you get your signer set up, you'll need to generate a new private key. The stacks-cli provides a mechanism for quickly generating a new account keychain via a simple CLI interface. The linked guide shows how to create one of those accounts on testnet.

Save the generated account information securely; you'll need it later.

What should the networking setup look like?

Signers are intended to work with a local node. The node<->signer connection is not run over SSL, which means you can be exposed to a man-in-the-middle attack if your signer and node are hosted on separate machines. Ensure your signer isn't allowing requests from the public internet. We recommend having the signer and node running locally on the same machine or using internal networking between them.

---

Create a Configuration File

Create a file named signer-config.toml. Populate it with the example signer config file contents from the Sample Configuration Files page. Each field is described on that page.

---

Running the Signer

Two options: Docker (recommended) or binary. Binaries are available on the Stacks Core releases page.

Running the Signer with Docker

You can run the signer as a Docker container using the blockstack/stacks-signer:3.1.0.0.5.0 image.

Requirements when running the container:

• The port configured as the endpoint (example: 30000) must be exposed to your Stacks node (endpoint should not be public).

• A volume with at least a few GB available that contains the folder specified by your db_path (example: /var).

• Mount your signer-config.toml file as a volume.

Example docker run command:

IMG="blockstack/stacks-signer"
VER="3.1.0.0.5.0"
STX_SIGNER_PATH="./"
STX_SIGNER_DATA="$STX_SIGNER_PATH/data"
STX_SIGNER_CONFIG="$STX_SIGNER_PATH/signer-config.toml"

docker run -d \
    -v $STX_SIGNER_CONFIG:/config.toml \
    -v $STX_SIGNER_DATA:/var/stacks \
    -p 30000:30000 \
    -e RUST_BACKTRACE=full \
    -e BLOCKSTACK_DEBUG=0 \
    --name stacks-signer \
    $IMG:$VER \
    stacks-signer run \
    --config /config.toml

If you get an error about the manifest not found or the image platform not matching the host platform, you probably are running on an architecture other than x64. Add --platform=linux/amd64 to the command (for example, on M1 Mac).

Or, using a custom Dockerfile:

FROM blockstack/stacks-signer:3.1.0.0.5.0
COPY signer-config.toml /config.toml
EXPOSE 30000
CMD ["stacks-signer", "run", "--config", "/config.toml"]

Running the Signer as a Binary

Download the pre-built binaries from the Stacks Core releases page on Github, unzip the archive for your architecture. It includes the stacks-signer binary.

Run the signer:

stacks-signer run --config ../signer-config.toml

(Replace ../signer-config.toml with the actual path to your config.)

---

Verify the Signer is Running

List running containers:

docker ps

Check the container logs:

docker logs <container-id>

You should see:

Signer spawned successfully. Waiting for messages to process...

You may also see a warning like:

WARN [1712003997.160121] [stacks-signer/src/runloop.rs:247] [signer_runloop] Signer is not registered for reward cycle 556. Waiting for confirmed registration...

This means your signer is running and awaiting registration; proceed to set up the Stacks node and then begin stacking.

You may see messages saying the signer is not registered for the current or next reward cycle. This is normal until the prepare phase for your chosen reward cycle; assuming you meet the stacking minimum, the signer will be registered during that phase.

---

Set Up Your Bitcoin Node

Optional but recommended to improve signer health and performance.

Guides:

• Run a full Bitcoin node: https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-bitcoin-node

• Run a pruned Bitcoin node: https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-pruned-bitcoin-node

---

Set Up Your Stacks Node

Start the Stacks node after the signer is running. The node will not run unless it can send events to the signer.

Stacks Node Configuration

Create node-config.toml. See the Sample Configuration Files page for the full contents.

Important fields to change:

• working_dir: directory where the node persists data

• auth_token: authentication token used by signer (must match signer auth_password)

• events_observer.endpoint: host and port where your signer listens (example: 127.0.0.1:30000 or stacks-signer.local:30000)

Start with an archive

Starting from an archive snapshot is much faster than syncing from genesis. Archives are at https://archive.hiro.so.

Example to download and extract the latest mainnet snapshot:

curl -# https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz -o stacks-snapshot.tar.gz
tar -zxvf stacks-snapshot.tar.gz

This creates a mainnet folder where downloaded. Set working_dir to the parent directory containing mainnet.

See best practices for snapshots: ../best-practices-to-snapshot-the-chainstate.md

Run a Stacks Node with Docker

Use the blockstack/stacks-core image (example tag: 3.1.0.0.13).

When running the container:

• Expose the port configured for p2p_bind to the internet.

• Make the port configured for rpc_bind accessible by your signer.

• working_dir needs 500 GB–1 TB storage.

• Include your node-config.toml.

Example docker run:

IMG="blockstack/stacks-core"
VER="3.1.0.0.13"
STX_NODE_CONFIG="./node-config.toml"

docker run -d \
    -v $STX_NODE_CONFIG:/config.toml \
    -v /var/stacks \
    -p 20443:20443 \
    -p 20444:20444 \
    -e RUST_BACKTRACE=full \
    --name stacks-node \
    $IMG:$VER \
    stacks-node start \
    --config /config.toml

Or with a custom Dockerfile:

FROM blockstack/stacks-core:3.1.0.0.13
COPY node-config.toml /config.toml
EXPOSE 20444
EXPOSE 20443
CMD ["stacks-node", "start", "--config", "/config.toml"]

If you get connection refused errors, you may need to point events_observer.endpoint to the Docker signer container. If using default Docker bridge mode, localhost inside the container is not the host. Point the endpoint to the Docker host or the signer container hostname accordingly.

Run a Stacks Node with a Binary

Download the pre-built stacks-node binary from the Stacks Core releases.

Start the node:

./stacks-node start --config node-config.toml

Verify Stacks Node is Running

Typical startup logs:

Mar  6 19:35:08.212848 INFO stacks-node 0.1.0
Mar  6 19:35:08.213084 INFO Loading config at path ./Stacks-config.toml
Mar  6 19:35:08.216674 INFO Registering event observer at: localhost:30000
Mar  6 19:35:08.221603 INFO Migrating sortition DB to the latest schema version
Mar  6 19:35:08.224082 INFO Migrating chainstate DB to the latest schema version
Mar  6 19:35:08.227404 INFO Start syncing Bitcoin headers, feel free to grab a cup of coffee, this can take a while

Ensure you see the Registering event observer at XXX log with your signer endpoint. Once Bitcoin headers are synced, you can GET /v2/info on the node RPC endpoint (default port 20443).

You may see many logs while syncing; refer to How to Read the Signer Logs if concerned.

---

Next Steps: Stacking

Once your signer and Stacks node are running and verified, the next step is to stack STX to register your signer for a reward cycle. See the Stacking STX guide for complete instructions on solo stacking, delegated stacking, and managing your keys.

You will need to generate a signer signature before making any stacking transaction.