denex-network-manager

A Testcontainers-style SDK and Deno CLI for running Canton Network LocalNets from a single YAML file.

denex-network-manager is for local Canton/Splice development: start a Super Validator, one or more regular validators, Keycloak, PostgreSQL, Nginx, and the web UIs without maintaining the upstream LocalNet config tree yourself.

Pre-1.0 beta: This is a beta release. The API may change in minor versions (0.x). Check the CHANGELOG before upgrading.

Requirements

• Docker running locally
• Deno 2.0+ for the CLI
• Deno 2.0+, Node.js 18+, or Bun for the SDK/API layer

The CLI is Deno-only because it uses Cliffy and Deno.* APIs. The SDK and low-level API use node: built-ins and are intended to work on Deno, Node.js, and Bun.

Bun caveat: Bun does not support Docker Unix sockets reliably through node:http. If you use the SDK from Bun, configure Docker to listen on a TCP socket.

This release targets Splice/Canton version 0.6.6. To use a different version, pass images to LocalNetOptions or LocalNetBuilder.

Installation

CLI

Install the pre-compiled dnm binary. No Deno required:

curl -fsSL https://raw.githubusercontent.com/denex-io/denex-network-manager/main/install.sh | sh

This installs to ~/.dnm/bin and verifies the download against the release checksums. Set DNM_INSTALL_DIR to install elsewhere, or DNM_VERSION (e.g. v0.1.0-beta.1) to pin a version.

Prefer not to pipe a script to your shell? Download the archive for your platform from the latest release, verify it against SHA256SUMS, then extract dnm onto your PATH. Builds are provided for Linux x64/arm64, macOS x64/arm64, and Windows x64 (dnm-win-x64.zip).

Or run from source (requires Deno 2.0+ and a repo checkout):

deno install --global --allow-all --config deno.json --name dnm src/cli/mod.ts

SDK

The npm package contains the SDK only — use one of the CLI options above for dnm.

Node.js / npm:

npm install @denex/network-manager@beta

Bun:

bun add @denex/network-manager@beta

Then import:

import { LocalNet, LocalNetBuilder } from '@denex/network-manager/sdk';

Quick Start

Create localnet.yaml:

version: '1.0'

validators: 2

auth:
  keycloak:
    admin: admin
    password: admin

Start the LocalNet:

dnm start

Check status and endpoints:

dnm status
dnm env
dnm credentials

Stop or destroy it:

dnm stop
dnm destroy --force

destroy removes containers, networks, volumes, and .localnet/<instance> data. Without --force, it asks for confirmation.

CLI

dnm --help
dnm <command> --help

Commands:

| Command | Description | | -------------- | -------------------------------------------------------- | | start | Start LocalNet containers | | stop | Stop all containers gracefully | | status | Show container state and health | | destroy | Remove containers, networks, volumes, and generated data | | init | Initialize users and parties on a running LocalNet | | config | Generate localnet.yaml interactively | | parties | List parties across validators | | packages | List uploaded DAR packages | | env | Show API URLs, auth config, and DSO party ID | | credentials | Show web UI login credentials | | instances | List running LocalNet instances | | entitlements | List users with their rights | | discovery | Run the multi-instance discovery HTTP server |

Only start and config accept --config <path>. State commands attach to running Docker containers through labels. If multiple instances are running, pass --instance <id>.

Useful options:

dnm config -y -o localnet.yaml
dnm start --instance demo --timeout 300000
dnm start --skip-init
dnm start --skip-health-checks
dnm env --json
dnm env --shell
dnm credentials --json

Web UIs And Credentials

Default ports use base port 5000:

| URL | Service | Default login | | ------------------------------ | ----------------------------- | ----------------------------- | | http://sv.localhost:5080 | Super Validator management UI | sv / sv | | http://scan.localhost:5080 | Scan explorer | sv / sv if prompted | | http://wallet.localhost:5080 | SV wallet | sv / sv | | http://wallet.localhost:5180 | Validator 1 wallet | validator-1 / validator-1 | | http://wallet.localhost:5280 | Validator 2 wallet | validator-2 / validator-2 |

For custom validators, the default wallet user is the validator name with the same value as the password. YAML-defined users also use id as the default password.

The auth.keycloak.admin and auth.keycloak.password values configure the persistent Keycloak master realm admin. They are not validator wallet credentials.

Configuration

The Super Validator is always created automatically. Configure only regular validators.

Minimal config:

version: '1.0'
validators: 2
auth:
  keycloak:
    admin: admin
    password: admin

Detailed config:

version: '1.0'
basePort: 6000

validators:
  - name: app
    parties:
      - hint: app-operator
        displayName: App Operator
    users:
      - id: app-operator
        primaryParty: app-operator
      - id: app-admin
        rights: [ParticipantAdmin]
  - name: users-val
    parties:
      - hint: alice
      - hint: bob
    users:
      - id: alice
        primaryParty: alice
      - id: bob
        primaryParty: bob
        parties:
          - hint: alice
            rights: [CanReadAs]

auth:
  keycloak:
    admin: admin
    password: admin

User rights are split into participant-wide rights and per-party rights:

• Participant-wide: ParticipantAdmin, CanReadAsAnyParty, CanExecuteAsAnyParty, IdentityProviderAdmin
• Per-party: CanActAs, CanReadAs, CanExecuteAs

primaryParty grants CanActAs on that party. Entries in users[].parties grant additional per-party rights and default to CanActAs when rights is omitted. Party hints referenced by users are auto-allocated if they are not listed under the validator's top-level parties.

Party hints supplied by users are normalized for Canton when needed. Validator operator party hints are generated separately from validator names.

Port Allocation

Ports use basePort with +100 increments per validator:

| Service | SV | Validator 1 | Validator 2 | | ------------------- | ---- | ----------- | ----------- | | HTTP health | 5000 | 5100 | 5200 | | Ledger API | 5001 | 5101 | 5201 | | Admin API | 5002 | 5102 | 5202 | | Validator Admin API | 5003 | 5103 | 5203 | | gRPC | 5061 | 5161 | 5261 | | JSON API | 5075 | 5175 | 5275 | | Web UI | 5080 | 5180 | 5280 | | Keycloak | 5082 | - | - |

With basePort: 6000, the same layout starts at 6000, 6100, 6200, and so on.

SDK Usage

Use @denex/network-manager/sdk for the common surface:

import { LocalNet, LocalNetBuilder } from '@denex/network-manager/sdk';

const net = await LocalNet.fromConfig('./localnet.yaml', {
  instanceId: 'demo',
});

await net.start();

const env = await net.getEnvironment();
const credentials = await net.getCredentials();
const parties = await net.getParties();

await net.stop();

Build config in code:

const config = LocalNetBuilder.create()
  .addValidator('app', {
    parties: ['app-operator'],
    users: [{ id: 'app-operator', primaryParty: 'app-operator' }],
  })
  .addValidator('users-val', { parties: ['alice', 'bob'] })
  .withBasePort(6000)
  .withAuth('admin', 'admin')
  .build();

const net = await LocalNet.fromConfig(config);
await net.start();

Attach to a running instance without a config file:

const net = await LocalNet.fromInstanceId('demo');
const status = await net.status();
const snapshot = await net.getSnapshot();

Create users and upload DARs after startup:

await net.createUser('alice', 'users-val', {
  primaryParty: 'alice',
  parties: [{ hint: 'bob', rights: ['CanReadAs'] }],
});

const packageId = await net.uploadDar('./my-app.dar');
await net.uploadDar('./my-app.dar', ['app', 'users-val']);

Note: DAR packages listed in the packages: config field are validated on load but are not uploaded automatically on startup. Call net.uploadDar(path) after start, or use dnm to upload after the network is running.

createUser provisions the ledger user, Keycloak user, and wallet onboarding. It is idempotent per side, so retries converge after partial failures.

Advanced users can import the full API from @denex/network-manager, including CantonClient, ValidatorAdminClient, generators, schemas, Docker helpers, and discovery utilities.

SDK Quick Start

import { LocalNetBuilder } from '@denex/network-manager/sdk';

const net = await new LocalNetBuilder()
  .withValidators(1)
  .build();

await net.start({ onProgress: console.log });
const env = await net.getEnvironment();
console.log(env.sv.endpoints);
await net.destroy();

Discovery Server

The discovery server is a separate foreground process for querying running instances over HTTP. It is not started from localnet.yaml; the discovery config field is deprecated.

dnm discovery serve --port 3100 --host 127.0.0.1

Useful routes:

• GET /health
• GET /instances
• GET /instances/:id/status
• GET /instances/:id/env
• GET /instances/:id/parties
• GET /instances/:id/packages
• GET /instances/:id/snapshot

Example:

curl http://127.0.0.1:3100/instances
curl http://127.0.0.1:3100/instances/demo/env

Troubleshooting

Container names are prefixed with the instance ID (default: default). Use dnm status to list running container names.

502 Bad Gateway on API routes: the splice container is likely crash-looping. Check docker logs default-splice for fatal errors. A bad validator config can take all Splice APIs offline because SV, Scan, and validator apps run in one process.

401 Unauthorized from wallet APIs: verify Keycloak realm names. Validator realm names are title-cased from validator names, for example validator-1 becomes Validator1 and alice-validator becomes AliceValidator. Check docker logs default-keycloak for realm import errors.

Web UI loads but spins forever: the static UI is reachable but the backend API is unhealthy or unreachable. Check dnm status and the relevant container logs.

Splice reports "Node name is too long": use shorter validator names. Splice limits generated node names to 30 characters.

Development

Working from a source checkout requires Deno 2.0+.

# Run CLI from source
deno task cli start

# Type-check, lint, test
deno task check
deno task lint
deno task test:unit
deno task test:smoke

Integration tests require Docker and may start containers. Unit tests do not require Docker.

Useful development references are upstream, not vendored here:

• Splice: https://github.com/canton-network/splice
• Canton Network Quickstart: https://github.com/digital-asset/cn-quickstart

If you need local checkouts, clone them under .references/:

mkdir -p .references
git clone https://github.com/canton-network/splice .references/splice
git clone https://github.com/digital-asset/cn-quickstart .references/cn-quickstart

.references/ is ignored by git.

License

Copyright Cumberland Applications LLC 2026. Licensed under the Apache License, Version 2.0.