> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canton.network/llms.txt
> Use this file to discover all available pages before exploring further.

# LocalNet

> Run a multi-validator Canton Network locally with Docker Compose for development and integration testing.

LocalNet provides a straightforward topology comprising three participants, three validators, a PostgreSQL database, and several web applications (wallet, sv, scan) behind an NGINX gateway. Each validator plays a distinct role within the Splice ecosystem:

* **app-provider**: for the user operating their application
* **app-user**: for a user wanting to use the app from the App Provider
* **sv**: for providing the Global Synchronizer and handling AMT

Designed primarily for development and testing, LocalNet is not intended for production use.

LocalNet is provided as part of the [cn-quickstart](https://github.com/digital-asset/cn-quickstart) repository.

## What LocalNet Provides

* Three validators: Super Validator (SV), App Provider, and App User
* A local synchronizer with sequencer and mediator
* Canton Coin wallet services for each validator
* PQS (Participant Query Store) instances
* JSON API endpoints
* Keycloak for authentication (optional)
* Observability stack: Grafana, Prometheus, Loki (optional)

## Setup

From the cn-quickstart repository:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/digital-asset/cn-quickstart
cd cn-quickstart
direnv allow
cd quickstart
make install-daml-sdk
make setup
make build
make start
```

`make setup` prompts you to select a deployment profile and generates the appropriate `.env.local` configuration. `make build` compiles the Daml contracts, Java backend, and React frontend. `make start` launches the Docker Compose stack.

Check the status of running containers:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
make status
```

Stop the environment:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
make stop
```

## Network Topology

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    subgraph LocalNet
        SV[Super Validator<br>Port prefix: 4xxx]
        PROV[App Provider<br>Port prefix: 3xxx]
        USER[App User<br>Port prefix: 2xxx]
        SEQ[Sequencer]
        MED[Mediator]
    end

    SV --> SEQ
    PROV --> SEQ
    USER --> SEQ
    SEQ --> MED
```

Each validator runs a participant, wallet services, and supporting infrastructure. The Super Validator also runs the synchronizer components (sequencer and mediator) and the Splice SV app.

## Port Conventions

## Exposed Ports

The following section details the ports used by various services. The default database port is **DB\_PORT=5432**.

Other ports are generated using specific patterns based on the validator:

* For the Super Validator (sv), the port is specified as `4${PORT_SUFFIX}`.
* For the App Provider, the port is specified as `3${PORT_SUFFIX}`.
* For the App User, the port is specified as `2${PORT_SUFFIX}`.

These patterns apply to the following ports suffixes:

* **PARTICIPANT\_LEDGER\_API\_PORT\_SUFFIX**: 901
* **PARTICIPANT\_ADMIN\_API\_PORT\_SUFFIX**: 902
* **PARTICIPANT\_JSON\_API\_PORT\_SUFFIX**: 975
* **VALIDATOR\_ADMIN\_API\_PORT\_SUFFIX**: 903
* **CANTON\_HTTP\_HEALTHCHECK\_PORT\_SUFFIX**: 900
* **CANTON\_GRPC\_HEALTHCHECK\_PORT\_SUFFIX**: 961

UI Ports are defined as follows:

* **APP\_USER\_UI\_PORT**: 2000
* **APP\_PROVIDER\_UI\_PORT**: 3000
* **SV\_UI\_PORT**: 4000

## Application UIs

* **App User Wallet UI**

  > * **URL**: `http://wallet.localhost:2000`
  > * **Description**: Interface for managing user wallets.

* **App Provider Wallet UI**

  > * **URL**: `http://wallet.localhost:3000`
  > * **Description**: Interface for managing user wallets.

* **Super Validator Web UI**

  > * **URL**: `http://sv.localhost:4000`
  > * **Description**: Interface for super validator functionalities.

* **Scan Web UI**

  > * **URL**: `http://scan.localhost:4000`
  > * **Description**: Interface to monitor transactions.

<Note>
  <span class="title-ref">LocalNet</span> rounds may take up to 6 rounds (equivalent to one hour) to display in the scan UI.
</Note>

In most scenarios, the `*.localhost` domains (e.g., `http://scan.localhost`) will resolve to your local host IP `127.0.0.1`. There are some situations where the resolution does not occur and the solution is to add entries to your `/etc/hosts` file. For example, to resolve `http://scan.localhost` and `http://wallet.localhost` add these entry to the file:

```
127.0.0.1   scan.localhost
127.0.0.1   wallet.localhost
```

## Default Wallet Users

* **App User**: app-user
* **App Provider**: app-provider
* **SV**: sv

For example, the App User's Ledger API is at `localhost:2901`, and the App Provider's JSON API is at `localhost:3975`.

<Warning>
  The Admin API and PostgreSQL ports are exposed for development convenience. Do not expose these ports in non-local deployments.
</Warning>

## Configuration Options

### Deployment Profiles

`make setup` offers deployment profiles that control which optional services are included:

* **Minimal** -- Core validators and synchronizer only
* **Standard** -- Adds PQS, JSON API, and authentication
* **Full** -- Adds observability (Grafana, Prometheus, Loki)

### Environment Variables

The `.env` file in the `quickstart/` directory contains version numbers, feature flags, and service configuration. Create a `.env.local` file (not tracked by git) to override settings locally.

### Docker Compose Modules

LocalNet is built from modular Docker Compose layers in `docker/modules/`:

* `localnet/` -- Base infrastructure (validators, synchronizer)
* `auth/` -- Keycloak authentication
* `observability/` -- Grafana, Prometheus, Loki
* `pqs/` -- Participant Query Store instances
* `app/` -- Application services (backend, frontend)

## Health Checks

Verify that validators are healthy:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -f http://localhost:2903/api/validator/readyz  # App User
curl -f http://localhost:3903/api/validator/readyz  # App Provider
curl -f http://localhost:4903/api/validator/readyz  # Super Validator
```

An empty response indicates a healthy service.

## Multiple Synchronizers

LocalNet supports running multiple synchronizers side by side.

By default, a single synchronizer controlled by the Super Validator (sv) is active. This synchronizer simulates the **Global Synchronizer**.

To enable a second synchronizer called `app-synchronizer`, start LocalNet with the `multi-sync` Docker Compose profile (`--profile multi-sync`). The additional synchronizer has the following characteristics:

* It is managed by the `app-sequencer` and `app-mediator` nodes.
* It simulates a **private synchronizer**.
* Both the `app-provider` and `app-user` participants are cross-connected to the Global Synchronizer and the `app-synchronizer`.

## Using Non-Default Protocol Versions

The protocol version used in the LocalNet synchronizer and participants can be configured by setting the `CANTON_PROTOCOL_VERSION` environment variable to the required version prior to launching LocalNet. Non-stable protocol versions can be used for early testing, but require explicit opt-in. To enable that, export also an `ALPHA_PROTOCOL_VERSION_ENV=$LOCALNET_DIR/env/alpha-protocol-version.env` environment variable.

<Warning>
  Non-stable protocol versions are unreleased versions that are under development, and are subject to announced breaking changes. One implication of this is that this environment usually cannot be upgraded, and will therefore require a full reset for every change. Use only for early testing and development purposes.
</Warning>

## When to Use LocalNet vs Sandbox

**Use LocalNet** when you need to test:

* Multi-party workflows across separate validators
* Canton Coin transfers and traffic purchases
* Wallet integration
* Splice API interactions (Scan, Validator APIs)
* End-to-end flows with backend, frontend, and ledger

**Use the [Sandbox](/sdks-tools/development-tools/sandbox)** when you need:

* Fast iteration on contract logic
* Single-participant testing without Docker
* A lightweight environment for `dpm test` and Ledger API integration

## Related Pages

* [cn-quickstart](/sdks-tools/reference-projects/cn-quickstart) -- Repository overview and project structure
* [Sandbox](/sdks-tools/development-tools/sandbox) -- Lightweight single-node alternative
* [QuickStart walkthrough](/appdev/quickstart/running-the-demo) -- Step-by-step guide to running the demo application