Docker Compose Network

Use the Docker Compose stacks in the Stoffel repository when you need to run the networked runtime shape: coordinator, MPC parties, client input processes, node RPC addresses, identity material, backend selection, and persistent preprocessing or local stores. Compose is useful for local testing and for deploying a Stoffel MPC network to infrastructure you operate, including a developer-owned backend. The checked-in Compose files are examples, not app-ready deployment manifests: expect to read and heavily modify them for your application. For a first app loop, start with local MPC through the stoffel CLI or Rust SDK; move to Compose when you want explicit service topology, container boundaries, persistent stores, or backend integration.

What the Docker stacks provide

The Compose files make the runtime topology explicit and runnable:

Runtime piece	What to look for
Coordinator	A service that tracks the computation round, known parties, expected clients, output clients, and backend settings.
Leader party	Party `0`, which also acts as the bootstrap point for peer discovery in the local Compose network.
Other parties	Party processes with their own bind address, party ID, node certificate, key, and optional local/preprocessing store.
Client processes	Containers that submit client input values to node RPC endpoints and, when configured, receive outputs.
Program bytecode	A `.stflb` artifact mounted or packaged into the runtime image.
Identity material	Node and client certificates/keys used by the coordinator and parties.
Backend settings	Environment variables for HoneyBadger or AVSS and curve selection.

Source files

From the Stoffel repository:

File	Use it for
`Dockerfile`	Building the runtime image that packages `stoffel-run`, example bytecode, identity material, and the node entrypoint.
`docker/entrypoint.sh`	Understanding role-specific runtime flags for leader, party, bootnode, and client modes.
`docker/coordinator.Dockerfile`	Building the off-chain coordinator wrapper image.
`docker-compose.yml`	Five-party HoneyBadger run with coordinator and fixed local networking.
`docker-compose.coordinator.reserve-index.yml`	Coordinator, five parties, and two client containers using deterministic client index reservation.
`docker-compose.coordinator.reserve-index.preproc.yml`	Persistent preprocessing volumes layered on the reserve-index coordinator stack.
`docker-compose.avss.yml`	Five-party AVSS/DKG-style local-store testbed and curve selection examples.

Swap and adapt a Compose stack

Start by choosing the closest root Compose file, then copy it into your application or infrastructure repository before editing it. Do not patch the example in place and assume it now represents your app. The root files are runnable templates for Stoffel service roles; your app decides the bytecode, images, client services, network names, ports, identity material, storage, and backend settings. Use this adaptation order:

Choose the baseline stack. Use docker-compose.yml for a basic HoneyBadger coordinator/party run, docker-compose.coordinator.reserve-index.yml when your app has explicit client containers and client-slot assignment, add docker-compose.coordinator.reserve-index.preproc.yml when you need persistent preprocessing storage, or use docker-compose.avss.yml when you are exercising AVSS/local-store behavior.
Copy the Compose file and overlays. Keep the original root files as references. Edit an app-owned copy such as compose.stoffel.yml so your changes can live with the application deployment code.
Replace the program artifact. Build your application’s .stflb, package or mount it into the runtime container, and update STOFFEL_PROGRAM to the in-container path. If the entrypoint changes, update STOFFEL_ENTRY too.
Replace the image build. Swap the example image or build context for the image that contains your app’s bytecode, runtime wrapper, entrypoint script, certificates, and any app-specific client binaries.
Rewrite client services. Replace sample client containers and STOFFEL_INPUTS values with your own input/output client services. Match each service to the client slots and output recipients expected by your Stoffel program.
Update network addresses. Rename the Compose network, service names, coordinator address, party addresses, and STOFFEL_SERVERS entries so they match the hostnames your containers will actually resolve. Inside Compose, service names become DNS names; outside Compose, you may need routed hostnames, load balancers, or explicit published ports.
Change ports deliberately. Avoid copying host port mappings that collide with your backend or with multiple test networks on the same host. Keep container-internal ports aligned with service configuration, and change only the host-side published ports unless your runtime config also changes.
Replace identities and secrets. Generate deployment-specific node/client identity material and use secret management or protected environment files for tokens. Do not reuse checked-in local fixtures outside local tests.
Update volumes and stores. Replace example ids/, bytecode, preprocessing, and local-store mounts with app-owned directories or managed volumes. Decide which data must persist across restarts and which should be ephemeral.
Select backend settings. Set STOFFEL_MPC_BACKEND, STOFFEL_MPC_CURVE, STOFFEL_N_PARTIES, and STOFFEL_THRESHOLD to match the bytecode manifest, security target, and number of parties you are operating.
Validate from the container network. Run the adapted Compose stack, then check coordinator reachability, party-to-party reachability, client submission, output delivery, logs, and persistent store behavior from the same network namespaces the services use.

The main swaps usually look like this:

Example field	Replace with
Example `image:` or `build:`	Your runtime/client image or app-owned build context.
`STOFFEL_PROGRAM=/app/programs/...`	Your packaged `.stflb` path inside the runtime container.
Sample client service blocks	App-specific participant/output client services.
`STOFFEL_INPUTS` fixtures	Runtime input wiring owned by your client service.
Example service names and networks	Hostnames and networks used by your backend.
Checked-in `ids/` mounts	Deployment-specific identity material.
Example host ports	Ports that fit your backend, firewall, and local test matrix.
Example preprocessing/local-store volumes	App-owned persistent volumes or managed storage.

For example, a private matchmaking app should not keep the sample client containers unchanged. It should package the matchmaking .stflb, run participant clients that submit matchmaking payloads to the reserved client slots, expose only the coordinator/node endpoints those clients need, and mount identity and store paths owned by that deployment.

Switch from default programs to your program

The root Docker image ships with example bytecode under /app/programs/. The Compose files select one of those defaults with STOFFEL_PROGRAM, such as /app/programs/mpc_aes128_circuit.stflb for the HoneyBadger stack or /app/programs/avss_keygen.stflb for the AVSS stack. To run your own app, the path in STOFFEL_PROGRAM must point to a .stflb file that exists inside every party container. Use one of these two patterns.

Package the bytecode into an app image

Use this for repeatable local testing, staging, or a developer-owned backend.

Build your app’s bytecode with the same backend family you plan to run:

# From your Stoffel app project
stoffel build --backend honeybadger --parties 5 --threshold 1

# Or, for an AVSS app, choose the AVSS backend and curve you need
stoffel build --backend avss --field secp256k1 --parties 5 --threshold 1

Add an app-owned Dockerfile that starts from your Stoffel runtime base image or repeats the runtime stage from the root Dockerfile, then copies your bytecode into /app/programs/:

FROM my-stoffel-runtime-base:latest
COPY target/debug/my_app.stflb /app/programs/my_app.stflb

Update your app-owned Compose file so every party uses that image and program path:

x-party-common: &party-common
  image: my-stoffel-app-runtime:latest
  environment: &party-env
    STOFFEL_PROGRAM: /app/programs/my_app.stflb
    STOFFEL_ENTRY: main

Keep the backend settings aligned with the bytecode. A HoneyBadger-built program should run with STOFFEL_MPC_BACKEND=honeybadger; an AVSS-built program should run with STOFFEL_MPC_BACKEND=avss and the same curve selection you built for.

Mount the bytecode while iterating locally

Use this only for local development loops where you want to rebuild bytecode without rebuilding the runtime image.

x-party-common: &party-common
  volumes:
    - ./target/debug/my_app.stflb:/app/programs/my_app.stflb:ro
    - stoffel-local-store:/app/local-store
  environment: &party-env
    STOFFEL_PROGRAM: /app/programs/my_app.stflb
    STOFFEL_ENTRY: main

The left side of the mount is a host path; the right side is the in-container path. STOFFEL_PROGRAM must use the right-side path. If you run the stack from a different directory, update the host path or use an absolute path. Program switching is not only a filename change. If your program uses client inputs or sends outputs to clients, also update the client containers, STOFFEL_INPUTS, STOFFEL_CLIENT_INDEX, STOFFEL_SERVERS, output decoding, and any coordinator settings such as expected input/output clients. If the entry function is not main, set STOFFEL_ENTRY to the function you want every party to execute.

Run a HoneyBadger Compose network

Use docker-compose.yml when you want the HoneyBadger backend. The stack starts one coordinator and five MPC parties on the stoffel-net bridge. Each party receives STOFFEL_MPC_BACKEND=honeybadger, a party ID, coordinator address, node identity, RPC bind address, and the packaged program path. From a Stoffel source checkout, first render the Compose configuration you are about to run:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose -f docker-compose.yml config

Then start the HoneyBadger network:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose -f docker-compose.yml up --build

The default stack builds the runtime image, starts the coordinator, starts five party containers, and runs the packaged HoneyBadger program named by STOFFEL_PROGRAM. If you do not set STOFFEL_PROGRAM, the stack uses /app/programs/mpc_aes128_circuit.stflb. If you do not set STOFFEL_MPC_BACKEND, the stack uses honeybadger. To run your own HoneyBadger-compatible program, build or package your .stflb into the runtime image and point STOFFEL_PROGRAM at the in-container path:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
STOFFEL_PROGRAM=/app/programs/client_mul.stflb \
STOFFEL_MPC_BACKEND=honeybadger \
STOFFEL_MPC_CURVE=bls12-381 \
  docker compose -f docker-compose.yml up --build

For an app-owned copy, keep the same backend shape and update the app-specific fields:

services:
  party0:
    environment:
      STOFFEL_MPC_BACKEND: honeybadger
      STOFFEL_MPC_CURVE: bls12-381
      STOFFEL_PROGRAM: /app/programs/my_app.stflb
      STOFFEL_ENTRY: main
      STOFFEL_N_PARTIES: "5"
      STOFFEL_THRESHOLD: "1"
      STOFFEL_COORD_ADDR: coordinator:31415
      STOFFEL_RPC_ADDR: party0:16180

Apply the corresponding changes to every party service: keep party IDs unique, update bind/RPC addresses consistently, and replace node identities with the identities for that deployment. Inspect the running HoneyBadger services:

docker compose -f docker-compose.yml ps
docker compose -f docker-compose.yml logs -f coordinator party0

Stop and remove the local containers and network when you are done:

docker compose -f docker-compose.yml down

Run the coordinator/client reserve-index stack

Use this stack when you want to see the off-chain coordinator path with explicit client containers:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose -f docker-compose.coordinator.reserve-index.yml up --build

The stack contains:

one coordinator service on port 31415;
five MPC party services;
node RPC endpoints on ports such as 16180 through 16184 inside the Compose network;
two client containers that submit inputs to deterministic client indices;
node and client certificates mounted from ids/.

Swap client index assignment to check that the result follows the reserved index, not container start timing:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
STOFFEL_CLIENT0_INDEX=1 \
STOFFEL_CLIENT1_INDEX=0 \
  docker compose -f docker-compose.coordinator.reserve-index.yml up --build

Add persistent preprocessing storage:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose \
    -f docker-compose.coordinator.reserve-index.yml \
    -f docker-compose.coordinator.reserve-index.preproc.yml \
    up --build

Run an AVSS local-store stack

Use docker-compose.avss.yml when you want the AVSS backend. This stack starts five party containers on the stoffel-avss-net bridge, sets STOFFEL_MPC_BACKEND=avss for every party, and mounts a separate persistent local store volume for each party at /app/data. From a Stoffel source checkout, first render the AVSS Compose configuration:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose -f docker-compose.avss.yml config

Then start the AVSS network:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
  docker compose -f docker-compose.avss.yml up --build

The default AVSS stack runs /app/programs/avss_keygen.stflb. It leaves STOFFEL_MPC_CURVE empty unless you set it, so the runtime uses its default AVSS curve behavior. Select a curve or program with environment variables. For example, run the secp256k1 threshold-ECDSA fixture through AVSS:

STOFFEL_AUTH_TOKEN=replace-with-random-secret \
STOFFEL_MPC_CURVE=secp256k1 \
STOFFEL_PROGRAM=/app/programs/threshold_ecdsa_secp256k1.stflb \
  docker compose -f docker-compose.avss.yml up --build

For an app-owned copy, keep the AVSS backend setting and update the program, curve, party addresses, and local-store mounts:

services:
  party0:
    environment:
      - STOFFEL_MPC_BACKEND=avss
      - STOFFEL_MPC_CURVE=secp256k1
      - STOFFEL_PROGRAM=/app/programs/my_avss_app.stflb
      - STOFFEL_ENTRY=main
      - STOFFEL_N_PARTIES=5
      - STOFFEL_THRESHOLD=1
      - STOFFEL_LOCAL_STORE=/app/data/local.redb
    volumes:
      - my-avss-party0-local:/app/data

Apply the same backend, curve, party count, and threshold to every AVSS party. Keep each party’s STOFFEL_PARTY_ID, bind address, bootstrap address, and local-store volume distinct. Inspect the running AVSS parties and logs:

docker compose -f docker-compose.avss.yml ps
docker compose -f docker-compose.avss.yml logs -f party0

Stop the AVSS stack when you are done. Add -v only when you also want to remove the persistent local-store volumes:

docker compose -f docker-compose.avss.yml down
docker compose -f docker-compose.avss.yml down -v

Environment variables to understand

Variable	Meaning
`STOFFEL_AUTH_TOKEN`	Shared secret used for authenticated discovery/registration in these local stacks. Use a random value outside local demos.
`STOFFEL_ROLE`	Runtime mode: leader, party, bootnode, or client.
`STOFFEL_PARTY_ID`	Party index for an MPC node.
`STOFFEL_N_PARTIES`	Total party count.
`STOFFEL_THRESHOLD`	Fault/security threshold.
`STOFFEL_PROGRAM`	Bytecode path inside the runtime container.
`STOFFEL_ENTRY`	Entry function to execute.
`STOFFEL_COORD_ADDR`	Off-chain coordinator address.
`STOFFEL_RPC_ADDR`	Node RPC bind address used by clients.
`STOFFEL_SERVERS`	Client-side list of node RPC endpoints.
`STOFFEL_INPUTS`	Client input values submitted by a client container.
`STOFFEL_CLIENT_INDEX`	Client slot/index claimed by a client container.
`STOFFEL_CERT` / `STOFFEL_KEY`	Identity material for node or client mode.
`STOFFEL_PREPROC_STORE`	Persistent preprocessing store path.
`STOFFEL_LOCAL_STORE`	Persistent local store path.
`STOFFEL_MPC_BACKEND` / `STOFFEL_MPC_CURVE`	Backend and curve selection.

Use with your own backend

The Docker stacks are not only a local teaching aid. They are starting points that you adapt for a backend you control. For your own application, read the root Compose files and expect to heavily modify the Compose code and configuration rather than running the checked-in examples unchanged: build your app’s .stflb bytecode, mount or package it into the runtime image, configure coordinator and party addresses for your environment, wire your own client input/output services, and connect your app or client services to the exposed coordinator/node RPC endpoints. Use Compose when you want to own the deployment shape yourself:

local laptop or CI testing with the same service roles you plan to operate;
a developer-owned backend where the coordinator, parties, and clients run as containers;
staging environments that need persistent preprocessing or local stores;
operator runbooks that should start from concrete services rather than SDK-local execution.

The app-facing CLI and SDK workflows remain the quickest first loop. Compose shows and runs the services those workflows abstract away:

several MPC node processes;
a coordinator or bootstrap path;
configured parties and threshold;
client input submission;
bytecode execution;
explicit output reconstruction or delivery.

For a deployed backend, replace local-only defaults with your own operational choices: real secrets, identity material, network addresses, TLS/routing, observability, storage, upgrade process, and access controls. At minimum, review and update the Compose files, Docker image build, entrypoint environment, program bytecode path, client containers, identities, exposed ports, volumes, and backend-specific settings for your application. Treat the repository stacks as runnable templates that show the service roles, not as drop-in production manifests for every app.

Current caveats

These stacks are self-managed Compose deployments. They are suitable for local testing and developer-owned backend deployments, but they are not a managed hosting product.
Some coordinator paths are HoneyBadger/BLS12-381-specific while AVSS is exercised by a separate local-store stack.
The checked-in examples use fixed local subnets and local identity fixtures. Replace them with real identity, secret, network, and operations management when deploying outside a local test environment.
The runtime image packages selected example bytecode and sample client behavior. For your app, build your own .stflb, point STOFFEL_PROGRAM at it, and update the client/container code that submits inputs or receives outputs.

Introduction

Getting Started

Tutorials

The Stoffel CLI

MPC Backends

Deployment

StoffelLang

Stoffel VM

Architecture

What the Docker stacks provide

Source files

Swap and adapt a Compose stack

Switch from default programs to your program

Package the bytecode into an app image

Mount the bytecode while iterating locally

Run a HoneyBadger Compose network

Run the coordinator/client reserve-index stack

Run an AVSS local-store stack

Environment variables to understand

Use with your own backend

Current caveats

Next steps

​What the Docker stacks provide

​Source files

​Swap and adapt a Compose stack

​Switch from default programs to your program

​Package the bytecode into an app image

​Mount the bytecode while iterating locally

​Run a HoneyBadger Compose network

​Run the coordinator/client reserve-index stack

​Run an AVSS local-store stack

​Environment variables to understand

​Use with your own backend

​Current caveats

​Next steps

What the Docker stacks provide

Source files

Swap and adapt a Compose stack

Switch from default programs to your program

Package the bytecode into an app image

Mount the bytecode while iterating locally

Run a HoneyBadger Compose network

Run the coordinator/client reserve-index stack

Run an AVSS local-store stack

Environment variables to understand

Use with your own backend

Current caveats

Next steps