> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-jarekr-cache-jwks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# dpm (Daml Package Manager)

> Command reference and configuration for dpm, the primary CLI tool for Canton development.

`dpm` is the command-line interface for Canton development. It manages SDK installation, project scaffolding, compilation, testing, code generation, and local development environments. Most Canton development workflows start with a `dpm` command.

## Pre-requisites

Dpm runs on Windows, macOS and Linux.  For full functionality, you must have installed:

1. [VS Code download](https://code.visualstudio.com/download)
2. JDK 17 or greater, installed and part of your `JAVA_HOME`.  If you do not already have a JDK installed, try OpenJDK or [Eclipse Adoptium](https://adoptium.net/).

## Installation

Install `dpm` usually involves downloading a single binary and adding it to your `PATH`.

When installing `dpm`, you can set the `DPM_HOME` environment variable to change the location where the SDK and any future updates are installed. The default is:

* `${HOME}/.dpm/` on Mac and Linux
* `%APPDATA%/.dpm/` on Windows

To install the latest version:

### Mac/Linux Installation

```shell theme={null}
curl https://get.digitalasset.com/install/install.sh | sh
```

### Windows Installation

Download and run the [windows installer](https://get.digitalasset.com/install/latest-windows.html), which will install the dpm sdk and set up the PATH variable for you.

### Manual Installation

If you prefer a more manual installation process, see [Manual Installation Instructions](#manual-installation-instructions).

### Installing dpm without an SDK

You can download the `dpm` binary which doesn't have any SDK bundled with it from the [releases page](https://github.com/digital-asset/dpm/releases).
You can then run `dpm install` or `dpm install package` described in the [next section](#project-management).

### Verifying the Installation

Once installed, verify the installation:

```bash theme={null}
dpm --version
```

## Command Reference

### Project Management

**`dpm init`** -- Initialize a new Daml project in the current directory. Creates a `daml.yaml` configuration file and a basic project structure.

You can manage SDK versions manually by using `dpm install`.  To install the SDK version specified in the daml.yaml, run:

```shell theme={null}
dpm install package
```

To install a specific SDK version, for example version `3.4.11`, run:

```shell theme={null}
dpm install 3.4.11
```

To see the active SDK version:

```shell theme={null}
dpm version --active
```

```shell theme={null}
3.4.11
```

To list the installed SDK versions, including the currently active one (marked with `*`):

```shell theme={null}
dpm version
```

```shell theme={null}
  3.4.10
* 3.4.11
```

To additionally list all the SDK versions that can be installed, as well as the installed versions:

```shell theme={null}
dpm version --all
```

To get the list in a machine readable format:

```shell theme={null}
dpm version --all -o json
```

```json theme={null}
 [
    {
        "version": "3.4.9",
        "remote": true
    },
    {
        "version": "3.4.10",
        "installed": true,
        "remote": true
    },
    {
        "version": "3.4.11",
        "installed": true,
        "remote": true,
        "active": true
    }
]
```

```bash theme={null}
dpm init
```

**`dpm new`** -- Create a new project from a template. Templates provide working examples that you can modify.

```bash theme={null}
dpm new my-project --template daml-intro-contracts
```

**`dpm add`** -- Add a dependency to your project. Updates `daml.yaml` with the new package reference.

```bash theme={null}
dpm add some-package
```

### Building and Testing

**`dpm build`** -- Compile Daml source files into a DAR (Daml Archive) file. The output goes to `.daml/dist/`.

```bash theme={null}
dpm build
```

For multi-package projects, build all sub-packages:

```bash theme={null}
dpm build --all
```

**`dpm test`** -- Run all Daml Script tests in the current package. Produces a summary with pass/fail status and coverage report.

```bash theme={null}
dpm test
```

**`dpm install`** -- Download and install the Daml SDK version specified in `daml.yaml`.

```bash theme={null}
dpm install
```

### Code Generation

**`dpm codegen-js`** -- Generate TypeScript/JavaScript bindings from a compiled DAR file.

```bash theme={null}
dpm codegen-js .daml/dist/my-project.dar -o generated-ts
```

**`dpm codegen-java`** -- Generate Java bindings from a compiled DAR file.

```bash theme={null}
dpm codegen-java .daml/dist/my-project.dar -o generated-java
```

### Development Environment

**`dpm sandbox`** -- Start a local Canton sandbox node. This runs a single-participant Canton instance with an in-memory ledger for testing.

```bash theme={null}
dpm sandbox
```

**`dpm studio`** -- Open Daml Studio (the VS Code extension) for the current project. This launches VS Code with the Daml extension activated.

```bash theme={null}
dpm studio
```

### Exploration

Use `--help` on any command to see available options:

```bash theme={null}
dpm --help
dpm build --help
dpm codegen-java --help
dpm inspect-dar --help
```

## Summary of `dpm` Commands

* `dpm build`:                    Build a Daml package or project

  This builds the Daml project according to the project config file `daml.yaml` (see [configuration files](#configuration-files)).

  In particular, it will use the dpm SDK (specified in the `sdk-version` field in `daml.yaml`) to resolve dependencies and compile the Daml project.

  Given a `daml.yaml` and `.daml` source files, the `dpm build` command will generate a .dar for this package. See [How to build Daml Archives](/appdev/reference/daml-language-reference#building-daml-archives) for how to define a package and build it to a DAR.

* `dpm test`:                     Test the current Daml project or the given files by running all test declarations.

  This runs all daml scripts defined within a package.

  Daml Scripts are top level values of type `Script ()`, from the `daml-script` package. This package mimics a Canton Ledger Client for quick iterative testing,
  and direct support within [Daml Studio](/sdks-tools/development-tools/daml-studio). The command runs these scripts against a reference Ledger called the IDE Ledger, which implements the core functionality of the Canton Ledger without the complexity of multi-participant setups.

  It is most useful for verifying the fundamentals of your ledger model, before moving onto integration testing via the Ledger API directly, or the Daml Codegen.  `dpm test` also provides code coverage information for templates and choices used.

* `dpm clean`:                    Clean a Daml package or project

  This removes any Daml artifact files created in your package during a daml build, including DARs.

* `dpm codegen-alpha-java`:       codegen (alpha) for java

* `dpm codegen-alpha-scala`:      codegen (alpha) for scala

* `dpm codegen-alpha-typescript`: codegen (alpha) for typescript

* `dpm codegen-java`:             Daml to Java compiler

* `dpm codegen-js`:               Daml to JavaScript compiler

* `dpm canton-console`:           Canton console client

* `dpm daml-shell`:               daml-shell client for PQS

* `dpm damlc`:                    Compiler and IDE backend for the Daml programming language

* `dpm docs`:                     Generate documentation for a daml package from its documentation comments

* `dpm init`:                     Initialize a `daml.yaml` project configuration file in the current directory

* `dpm install`:                  Install new SDK versions manually

* `dpm install package`:          Install the SDK(s) or opt-in components used by current project

* `dpm inspect-dar`:              Inspect a DAR archive

* `dpm new`:                      Create a new Daml package

* `dpm pqs`:                      participant query store

* `dpm sandbox`:                  Run full Canton installation in a single process

* `dpm script`:                   Daml Script Binary

* `dpm studio`:                   Launch Daml Studio

* `dpm upgrade-check`:            Check upgrade validity between package versions

To specify additional options for sandbox/navigator/the HTTP JSON API you can use
`--sandbox-option=opt`, `--navigator-option=opt` and `--json-api-option=opt`.

* `dpm validate-dar`              Validate a DAR archive

  Note that you need to update your [project config file](#project-management) to use the new version.

## Configuration Files

### daml.yaml

Every Daml project has a `daml.yaml` file at its root. If a `daml.yaml` file doesn't exist in your project, you can create one with:

```shell theme={null}
dpm init
```

It specifies the SDK version, project metadata, source directory, and dependencies.

```yaml theme={null}
sdk-version: 3.4.0
name: my-project
source: daml
version: 1.0.0
dependencies:
  - daml-prim
  - daml-stdlib
build-options:
  - --target=3.4
```

Key fields:

* `sdk-version` -- The Daml SDK version to use. `dpm install` downloads this version.
* `name` -- The package name, used in the output DAR filename
* `source` -- Directory containing Daml source files (typically `daml`)
* `dependencies` -- List of Daml library dependencies
* `build-options` -- Compiler flags (e.g., target LF version)

### multi-package.yaml

For projects with multiple Daml packages, a `multi-package.yaml` at the project root lists all sub-packages:

```yaml theme={null}
packages:
  - ./contracts
  - ./tests
  - ./scripts
```

Running `dpm build --all` from the root builds all listed packages in dependency order.

### dpm-config.yaml

The `dpm-config.yaml` file stores global `dpm` configuration such as SDK installation paths and registry settings. It is typically located in your home directory and rarely needs manual editing.

### `dpm` Global configuration (`dpm-config.yaml`)

Global configuration is stored at `${DPM_HOME}/dpm-config.yaml` and is optional. It can be used for purposes such as:

* **Registry URL** — Override the default OCI registry for SDK components.
* **Authentication** — Point to registry credentials.
* **Insecure registry** — Allow HTTP connections to a registry.

### Variable interpolation

Both `daml.yaml` and `dpm-config.yaml` support variable interpolation, which lets you avoid hardcoded values (such as registry URLs or credentials paths) and reference environment variables or other dynamic values.

## `daml` assistant to `dpm` migration steps

This section provides a step-by-step guide for projects originally built with the Daml assistant.

## Migration steps

1. **Install Dpm**

   Follow the [installation instructions](#installation) above.

2. **Verify Dpm is in your PATH**

```shell theme={null}
dpm version
```

3. **Remove** `~/.daml/bin` **from your PATH**

   Edit your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`, `~/.profile`) and remove any line that adds `~/.daml/bin` to your `PATH`

4. **Remove the Daml assistant**

```shell theme={null}
rm -rf ~/.daml
```

5. **Create a project configuration if needed**

   If a `daml.yaml` file doesn't already exist in your project, generate one:

```shell theme={null}
dpm init
```

6. **Replace** `daml` **commands with** `dpm`

   Most commands map directly. See the [command migration table](/sdks-tools/cli-tools/dpm#command-migration-table) below.

   Six `daml` commands have been removed and replaced with Declarative API, Canton Console, JSON API, and/or gRPC API calls. See [removed command replacements](/sdks-tools/cli-tools/dpm#removed-command-replacements) for full details.

7. **Review project configuration**

   Review your `daml.yaml` to ensure it is compatible with dpm. Audit parent directories for stale `daml.yaml` files. Delete orphan or invalid files.

8. **Review global configuration** (optional)

   Review or create `${DPM_HOME}/dpm-config.yaml` if you need to customize registry, authentication, or other global settings.

9. **Set up variable interpolation** (optional)

   Use [variable interpolation](/sdks-tools/cli-tools/dpm#variable-interpolation) in your configuration files to avoid hardcoded values.

10. **Update CI/CD pipelines** (if applicable)

    Update any CI/CD pipeline scripts that reference `daml` commands to use the corresponding `dpm` commands instead.

## Command migration table

| daml command                     | dpm command                                                                     | purpose                           |
| -------------------------------- | ------------------------------------------------------------------------------- | --------------------------------- |
| daml new                         | dpm new                                                                         | Create a new Daml project         |
| daml build                       | dpm build                                                                       | Compile the Daml project          |
| daml test                        | dpm test                                                                        | Run tests for the Daml project    |
| daml install                     | dpm install                                                                     | Install Daml SDK components       |
| daml codegen java                | dpm codegen-java                                                                | Java code generation              |
| daml codegen js                  | dpm codegen-js                                                                  | TypeScript code generation        |
| daml damlc                       | dpm damlc                                                                       | Invoke the daml compiler          |
| daml studio                      | dpm studio                                                                      | Open project in Visual Studio     |
| daml sandbox                     | dpm sandbox                                                                     | Launch a Daml Sandbox             |
| `daml ledger allocate-parties`\_ | Use Declarative API – OR – JSON / gRPC API                                      | Allocate parties on a ledger      |
| `daml ledger list-parties`\_     | JSON / gRPC API                                                                 | list parties on a ledger          |
| `daml ledger upload-dar`\_       | Use Declarative API – OR – JSON / gRPC API                                      | Upload (and vet) dars on a ledger |
| `daml ledger fetch-dar`\_        | gRPC API                                                                        | Fetch a Dar from a ledger.        |
| `daml packages`\_                | JSON / gRPC API                                                                 | Package a Daml project            |
| `daml start`\_                   | dpm sandbox dpm build Use Declarative API – OR – JSON / gRPC to upload/allocate | Start a local Daml Ledger         |

## Removed command replacements

The following `daml` commands have no direct `dpm` equivalent. Use the Declarative API, Canton Console, JSON API, or gRPC API instead.

### `daml ledger allocate-parties`

| Method          | Details                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Declarative API | `canton.parameters.enable-alpha-state-via-config = yes` with `canton.participants.sandbox.alpha-dynamic { parties = [{ party = "Alice", synchronizers = ["mysync"] }, { party = "Bob" }] }` |
| Canton Console  | `ledger_api.parties.allocate(...)`                                                                                                                                                          |
| JSON API        | `POST /v2/parties/`                                                                                                                                                                         |
| gRPC            | `PartyManagementService.AllocateParty`                                                                                                                                                      |

### `daml ledger list-parties`

| Method         | Details                                        |
| -------------- | ---------------------------------------------- |
| Canton Console | `ledger_api.parties.list()`                    |
| JSON API       | `GET /v2/parties` or `GET /v2/parties/{party}` |
| gRPC           | `PartyManagementService.ListKnownParties`      |

### `daml ledger upload-dar`

| Method          | Details                                                                                                                                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Declarative API | `canton.parameters.enable-alpha-state-via-config = yes` with `canton.participants.sandbox.alpha-dynamic.dars = [{ location = "./my-asset.dar" }, { location = "https://path.to/repo/token.dar", request-headers = { AuthenticationToken : "mytoken" } }]` |
| Canton Console  | `ledger_api.packages.upload_dar(...)`                                                                                                                                                                                                                     |
| JSON API        | `POST /v2/dars/`                                                                                                                                                                                                                                          |
| gRPC            | `PackageManagementService.UploadDarFile`                                                                                                                                                                                                                  |

### `daml ledger fetch-dar`

| Method   | Details                         |
| -------- | ------------------------------- |
| JSON API | `GET /v2/packages/{package-id}` |
| gRPC     | `PackageService.GetPackage`     |

### `daml packages`

| Method         | Details                                                      |
| -------------- | ------------------------------------------------------------ |
| Canton Console | `ledger_api.packages.list()`                                 |
| JSON API       | `GET /v2/packages` or `GET /v2/packages/{package-id}/status` |
| gRPC           | `PackageService.ListPackages`                                |

### `daml start`

Replace with `dpm sandbox` combined with `dpm build`. Use the Declarative API or JSON/gRPC API to upload DARs and allocate parties as needed.

See `dpm sandbox` for details on running a local Canton installation.

## Publishing Components

<Note>
  This functionality is available in DPM version 1.0.13 or later (or bundled with SDK 3.5 or later).
</Note>

To share or use your Component in various projects, you can publish it to a repository:

```shell theme={null}
    dpm publish component oci://<destination>:<strict semantic version> \
        --platform generic="/path/to/component/directory"


```

For example:

```shell theme={null}
    dpm publish component oci://example.com/my/components/foo:1.0.0 \
        --platform generic="~/component-foo"

```

This publishes version `1.0.0` of `foo` as OCI to `example.com/my/components/foo:1.0.0`.

For multi-platform components, provide a directory for each platform:

```shell theme={null}
    dpm publish component oci://example.com/my/components/foo:1.0.0 \
        --platform linux/arm64="/some/directory" \
        --platform windows/amd64="/another/directory"

```

See the `dpm publish component --help` command for more available options.

You can also view the published versions and tags of a component:

```shell theme={null}
    dpm tags oci://example.com/my/components/foo

```

## Typical Workflow

A common development cycle with `dpm`:

```bash theme={null}
# 1. Set up the project
dpm new my-app --template daml-intro-contracts
cd my-app
dpm install

# 2. Write Daml code, then compile
dpm build

# 3. Run tests
dpm test

# 4. Start a local sandbox for integration testing
dpm sandbox

# 5. Generate bindings for your backend
dpm codegen-java .daml/dist/my-app.dar -o generated-java
dpm codegen-js .daml/dist/my-app.dar -o generated-ts
```

## Related Pages

* [Daml SDK](/sdks-tools/sdks/daml-sdk) -- What the SDK includes and how versions work
* [Sandbox](/sdks-tools/development-tools/sandbox) -- Local testing environment started by `dpm sandbox`
* [Daml Studio](/sdks-tools/development-tools/daml-studio) -- VS Code extension launched by `dpm studio`
* [Daml Script](/sdks-tools/cli-tools/daml-script) -- Writing and running tests with `dpm test`

## Sandbox<span id="component-howtos-application-development-daml-sandbox" />

Sandbox is a program for running a Canton ledger with your Daml code. The ledger uses the simplest topology possible: a single Participant Node connected to a Synchronizer Node. Use the sandbox when you need access to a Canton ledger running your Daml code and matching the target Participant Node topology is not required.

### Install

Install the Sandbox by installing dpm.

### Configure

To configure the Sandbox, use the command line.

#### Command line configuration

To view all available command line configuration options for Sandbox, run `dpm sandbox --help` in your terminal:

```none theme={null}
Usage: dpm sandbox [--port ARG] [--admin-api-port ARG]
                    [--sequencer-public-port ARG] [--sequencer-admin-port ARG]
                    [--mediator-admin-port ARG] [--json-api-port ARG]
                    [--json-api-port-file PATH] [--canton-port-file PATH]
                    [--static-time | --wall-clock-time] [--canton-help]
                    [-c|--config FILE] [--port-file PATH] [--dar PATH] [ARG]

Available options:
  --json-api-port ARG      Port that the HTTP JSON API should listen on, omit to
                           disable it
  --json-api-port-file PATH
                           File to write canton json-api port when ready
  --canton-port-file PATH  File to write canton participant ports when ready
  --canton-help            Display the help of the underlying Canton JAR instead
                           of the Sandbox wrapper. This is only required for
                           advanced options.
  -c,--config FILE         Set configuration file(s). If several configuration
                           files assign values to the same key, the last value
                           is taken.
  --port-file PATH         File to write ledger API port when ready
  --dar PATH               DAR file to upload to sandbox
  --shutdown-stdin-close   Shut down when stdin is closed, disabled by default
  -h,--help                Show this help text
```

Any unrecognized command-line arguments will be treated as arguments to be supplied to the underlying Canton JAR. Display these options by running `dpm sandbox --canton-help` in your terminal.

#### Canton configuration

Behind the scenes, Sandbox runs an underlying Canton ledger with a default configuration file to initialize a participant named `sandbox`, a sequencer named `sequencer1`, and a mediator named `mediator1`.

Configure the underlying Canton ledger further in one of two ways:

* Specify additional configuration file(s) to apply on top of the default configuration using `--config filepath`. If several configuration files assign to the same key, the last value is taken.

* Set the value of a specific key with `-C key=value`. For example, to override the ledger-api port of the sandbox participant, the command would be:

  ```none theme={null}
  dpm sandbox -C canton.participants.sandbox.ledger-api.port=9999
  ```

#### Canton Declarative API

The declarative API allows specifying DARs, Parties and Users desired to be present on the Canton ledger. The ledger will automatically take care of uploading the DARs, and creating the parties and users.

* upload local DARs

```none theme={null}
canton.parameters.enable-alpha-state-via-config = yes
canton.parameters.state-refresh-interval = 5s

canton.participants.sandbox.alpha-dynamic.dars = [
  { location = "./my-asset.dar" },
]
```

### Operate

Start Canton with a single participant:

```none theme={null}
$ dpm sandbox
Starting Canton sandbox.
Listening at port 6865
Canton sandbox is ready.
```

#### Interacting with Sandbox's ledger

Once the sandbox is running, you may interact with it the same way you would for any Canton instance. For example, you may upload dars to it, or run scripts against it:

```none theme={null}
$ dpm sandbox --dar <path to DAR>
$ dpm script --ledger-host localhost --port 6865 --dar <path to DAR> --script-name <script name in DAR>
```

Because `dpm sandbox` is a Canton instance, all documentation for using Canton applies.

#### Connecting to Sandbox's console

Once you have a Sandbox running locally (i.e. after running `dpm sandbox`) you may connect to Sandbox remotely by running the `dpm canton-console` command in a separate terminal:

```none theme={null}
$ daml canton-console
   _____            _
  / ____|          | |
 | |     __ _ _ __ | |_ ___  _ __
 | |    / _` | '_ \| __/ _ \| '_ \
 | |___| (_| | | | | || (_) | | | |
  \_____\__,_|_| |_|\__\___/|_| |_|

  Welcome to Canton!
  Type `help` to get started. `exit` to leave.

@
```

You can quit the session by running the `exit` command.

#### Built-in documentation

The Canton console comes with built-in documentation. You can use the `help` command to get online documentation for top-level commands. Many objects in the console also have built-in help that you can access by invoking the `help` method on them.

For example, you can ask for help on the `health` object by typing:

```scala theme={null}
health.help
```

Or go more in-depth about specific items within that object, as in the following example:

```scala theme={null}
health.help("status")
```

#### Interact with the Sandbox

One of the objects available in the Canton console represents the Sandbox itself. The object is called `sandbox` and you can use it to interact with the Sandbox. For example, you can list the DARs loaded on the Sandbox by running the following command:

```scala theme={null}
sandbox.dars.list()
```

Among the various features available as part of the console, you can manage parties and packages, check the health of the Sandbox, perform pruning operations, and more. Consult the built-in documentation mentioned above and the main documentation for the Canton console to learn about further capabilities.

#### How it works

Canton offers a console where you can run administrative or debugging commands.

When you run the Sandbox using `dpm sandbox`, you are effectively starting an in-memory instance of Canton with a single sync domain and a single participant.

As such, you can interact with the running Sandbox using the console, just like you would in a production environment.

For an in-depth guide on how to use this tool against a production, staging or testing environment, consult the main documentation for the Canton console.

#### Testing your Daml contracts

Sandbox is primarily used as the first step in testing your Daml contracts in isolation

#### Run with authorization

By default, Sandbox accepts all valid Ledger API requests without performing any request authorization.

To start Sandbox with authorization using [JWT-based](https://jwt.io/) access tokens as described in the Authorization documentation, create a config file that specifies the type of authorization service and the path to the certificate, then supply that config file to Sandbox with `dpm sandbox --config auth.conf`.

```none theme={null}
canton.participants.sandbox.ledger-api.auth-services = [{
    // type can be
    //   jwt-rs-256-crt
    //   jwt-es-256-crt
    //   jwt-es-512-crt
    //   jwt-rs-256-jwks with an additional url
    //   unsafe-jwt-hmac-256 with an additional secret
    type = jwt-rs-256-crt
    certificate = my-certificate.cert
}]
```

The settings under `auth-services` are described in detail in [Authorization documentation](/appdev/deep-dives/authorization#Authorization)

#### Generate JSON web tokens (JWT)

To generate access tokens for testing purposes, use the [jwt.io](https://jwt.io/) web site.

#### Generate RSA keys

To generate RSA keys for testing purposes, use the following command

```none theme={null}
openssl req -nodes -new -x509 -keyout sandbox.key -out sandbox.crt
```

which generates the following files:

* `sandbox.key`: the private key in PEM/DER/PKCS#1 format
* `sandbox.crt`: a self-signed certificate containing the public key, in PEM/DER/X.509 Certificate format

#### Generate EC keys

To generate keys to be used with ES256 for testing purposes, use the following command

```none theme={null}
openssl req -x509 -nodes -days 3650 -newkey ec:<(openssl ecparam -name prime256v1) -keyout ecdsa256.key -out ecdsa256.crt
```

which generates the following files:

* `ecdsa256.key`: the private key in PEM/DER/PKCS#1 format
* `ecdsa256.crt`: a self-signed certificate containing the public key, in PEM/DER/X.509 Certificate format

Similarly, you can use the following command for ES512 keys:

```none theme={null}
openssl req -x509 -nodes -days 3650 -newkey ec:<(openssl ecparam -name secp521r1) -keyout ecdsa512.key -out ecdsa512.crt
```

#### Run with TLS

To enable TLS, you need to specify the private key for your server and the certificate chain. This enables TLS for both the gRPC Ledger API and the Canton Admin API. When enabling client authentication, you also need to specify client certificates which can be used by Canton’s internal processes. Note that the identity of the application will not be proven by using this method, i.e. the `application_id` field in the request is not necessarily correlated with the CN (Common Name) in the certificate. Below, you can see an example config. For more details on TLS, refer to Canton’s documentation on TLS configuration.

```none theme={null}
canton.participants.sandbox.ledger-api {
  tls {
    // the certificate to be used by the server
    cert-chain-file = "./tls/ledger-api.crt"
    // private key of the server
    private-key-file = "./tls/ledger-api.pem"
    // trust collection, which means that all client certificates will be verified using the trusted
    // certificates in this store. if omitted, the JVM default trust store is used.
    trust-collection-file = "./tls/root-ca.crt"
    // define whether clients need to authenticate as well (default not)
    client-auth = {
      // none, optional and require are supported
      type = require
      // If clients are required to authenticate as well, we need to provide a client
      // certificate and the key, as Canton has internal processes that need to connect to these
      // APIs. If the server certificate is trusted by the trust-collection, then you can
      // just use the server certificates. Otherwise, you need to create separate ones.
      admin-client {
        cert-chain-file = "./tls/admin-client.crt"
        private-key-file = "./tls/admin-client.pem"
      }
    }
  }
}
```

#### Dev Protocol

To enable the canton dev protocol:

```bash theme={null}
cat <<EOF
canton.participants.sandbox.parameters.alpha-version-support = true
canton.sequencers.sequencer1.parameters.alpha-version-support = true
canton.parameters {
    non-standard-config = yes
    alpha-version-support = yes
}
EOF > dev-protocol.conf

CANTON_PROTOCOL_VERSION=dev dpm sandbox -c dev-protocol.conf
```

### Troubleshoot

#### Failed to bind to address

By default, Sandbox reserves five ports for its Canton services:

* `6865` for the participant's Ledger API
* `6866` for the participant's Admin API
* `6867` for the sequencer's public API
* `6868` for the sequencer's admin API
* `6869` for the mediator's admin API

The Sandbox will also bind to the port specified in the `--json-api-port`, if any.

When one of these ports is already used by an existing process, Sandbox will emit an error that contains the following text:

```none theme={null}
Failed to bind to address /127.0.0.1:<port number>
```

This is most commonly either caused by an existing process that is already listening on that port, or if you do not have the permissions to bind to that address.

On Linux, the `lsof -n -i` command lists what processes are already listening to a port. For example, if an existing Java program is already listening to 6865, `lsof` would look as follows:

```none theme={null}
$ lsof -n -i
...
java       707977 username       77u  IPv6 67556378      0t0  TCP 127.0.0.1:6865 (LISTEN)
...
```

If killing the existing process isn't an option, or if you don't have the permission to bind to a given port, you can reconfigure the ports of a given node using the top-level options described below:

* Use --port= to override binding to `6865`
* Use --admin-api-port= to override binding to `6866`
* Use --sequencer-public-port= to override binding to `6867`
* Use --sequencer-admin-port= to override binding to `6868`
* Use --mediator-admin-port= to override binding to `6869`
* Use `--json-api-port` to change the port to which the JSON API binds.

#### SDK not installed

If the `daml.yaml` file of the project you are currently in specifies a version of the dpm SDK that is not installed, you may get the following error message:

```none theme={null}
SDK not installed. Cannot run command without SDK.
```

To fix this, you can:

* Install the SDK as instructed to by the error, or
* Change the SDK version in the project's `daml.yaml` file, or
* Change directories to be outside of the project, where the default Daml version that is already installed on your system will be used.

{/* COPIED_START source="docs-website:docs/replicated/dpm/3.5/manual-install.rst" hash="3c8275c7" */}

# Manual Installation Instructions

## Mac/Linux

If you cannot / wish not to use the shell script to install for Linux or OSX, you can alternatively install dpm manually by running this set of commands in your terminal:

```bash theme={null}
#get latest version number
VERSION="$(curl -sS "https://get.digitalasset.com/install/latest")"

# set your architecture to either amd64 | arm64
ARCH="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"

# set your OS to either darwin or linux
OS="$(uname | tr '[:upper:]' '[:lower:]')"

#pull down appropriate tarball for your OS and architecture
readonly TARBALL="dpm-${VERSION}-${OS}-${ARCH}.tar.gz"

# determine location of tarball to download
TARBALL_URL="https://get.digitalasset.com/install/dpm-sdk/${TARBALL}"

# make tmpdir
TMPDIR="$(mktemp -d)"

# download tarball
curl -SLf "${TARBALL_URL}" --output "${TMPDIR}/${TARBALL}" --progress-bar "$@"

# create directory to extract into
extracted="${TMPDIR}/extracted"
mkdir -p "${extracted}"

# untar to extracted directory
tar xzf "${TMPDIR}/${TARBALL}" -C "${extracted}" --strip-components 1

# bootstrap dpm
"${extracted}/bin/dpm" bootstrap "${extracted}"

# cleanup tmpdir
rm -rf "${TMPDIR}"
```

## Windows

Download and unpack the latest dpm sdk version's [archive (.zip)](https://get.digitalasset.com/install/latest-windows-archive.html), then:

```powershell theme={null}
# Extract the downloaded zip ($ZIP_PATH) to temp directory ($EXTRACTED)
# Avoid using the system's temp directory as the user may not have rights to it
New-Item -ItemType Directory -Path $EXTRACTED | Out-Null
Expand-Archive -Path $ZIP_PATH -DestinationPath $EXTRACTED

# Optionally, override the TMP and DPM_HOME environment variable to point to directories other than the default,
# as the user might not have rights to the default directories.
# (You might also want to persist these variables as DPM uses them on every invocation)
$env:TMP = "<user-owned temporary directory>"
$env:DPM_HOME = "<user-owned directory>"

& "$EXTRACTED\windows-amd64\bin\dpm.exe" bootstrap $EXTRACTED\windows-amd64
```