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:- VS Code download
- 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.
Installation
Installdpm 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
Mac/Linux Installation
Windows Installation
Download and run the windows installer, 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.Installing dpm without an SDK
You can download thedpm binary which doesn’t have any SDK bundled with it from the releases page.
You can then run dpm install or dpm install package described in the next section.
Verifying the Installation
Once installed, verify the installation: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:
3.4.11, run:
*):
dpm new — Create a new project from a template. Templates provide working examples that you can modify.
dpm add — Add a dependency to your project. Updates daml.yaml with the new package reference.
Building and Testing
dpm build — Compile Daml source files into a DAR (Daml Archive) file. The output goes to .daml/dist/.
dpm test — Run all Daml Script tests in the current package. Produces a summary with pass/fail status and coverage report.
dpm install — Download and install the Daml SDK version specified in daml.yaml.
Code Generation
dpm codegen-js — Generate TypeScript/JavaScript bindings from a compiled DAR file.
dpm codegen-java — Generate Java bindings from a compiled DAR file.
Development Environment
dpm sandbox — Start a local Canton sandbox node. This runs a single-participant Canton instance with an in-memory ledger for testing.
dpm studio — Open Daml Studio (the VS Code extension) for the current project. This launches VS Code with the Daml extension activated.
Exploration
Use--help on any command to see available options:
Summary of dpm Commands
-
dpm build: Build a Daml package or project This builds the Daml project according to the project config filedaml.yaml(see configuration files). In particular, it will use the dpm SDK (specified in thesdk-versionfield indaml.yaml) to resolve dependencies and compile the Daml project. Given adaml.yamland.damlsource files, thedpm buildcommand will generate a .dar for this package. See How to build 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 typeScript (), from thedaml-scriptpackage. This package mimics a Canton Ledger Client for quick iterative testing, and direct support within 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 testalso 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 adaml.yamlproject 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
--sandbox-option=opt, --navigator-option=opt and --json-api-option=opt.
-
dpm validate-darValidate a DAR archive Note that you need to update your project config file to use the new version.
Configuration Files
daml.yaml
Every Daml project has adaml.yaml file at its root. If a daml.yaml file doesn’t exist in your project, you can create one with:
sdk-version— The Daml SDK version to use.dpm installdownloads this version.name— The package name, used in the output DAR filenamesource— Directory containing Daml source files (typicallydaml)dependencies— List of Daml library dependenciesbuild-options— Compiler flags (e.g., target LF version)
multi-package.yaml
For projects with multiple Daml packages, amulti-package.yaml at the project root lists all sub-packages:
dpm build --all from the root builds all listed packages in dependency order.
dpm-config.yaml
Thedpm-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
Bothdaml.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
- Install Dpm Follow the installation instructions above.
- Verify Dpm is in your PATH
-
Remove
~/.daml/binfrom your PATH Edit your shell configuration file (e.g.,~/.bashrc,~/.zshrc,~/.profile) and remove any line that adds~/.daml/binto yourPATH - Remove the Daml assistant
-
Create a project configuration if needed
If a
daml.yamlfile doesn’t already exist in your project, generate one:
-
Replace
damlcommands withdpmMost commands map directly. See the command migration table below. Sixdamlcommands have been removed and replaced with Declarative API, Canton Console, JSON API, and/or gRPC API calls. See removed command replacements for full details. -
Review project configuration
Review your
daml.yamlto ensure it is compatible with dpm. Audit parent directories for staledaml.yamlfiles. Delete orphan or invalid files. -
Review global configuration (optional)
Review or create
${DPM_HOME}/dpm-config.yamlif you need to customize registry, authentication, or other global settings. - Set up variable interpolation (optional) Use variable interpolation in your configuration files to avoid hardcoded values.
-
Update CI/CD pipelines (if applicable)
Update any CI/CD pipeline scripts that reference
damlcommands to use the correspondingdpmcommands instead.
Command migration table
Removed command replacements
The followingdaml commands have no direct dpm equivalent. Use the Declarative API, Canton Console, JSON API, or gRPC API instead.
daml ledger allocate-parties
daml ledger list-parties
daml ledger upload-dar
daml ledger fetch-dar
daml packages
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
This functionality is available in DPM version 1.0.13 or later (or bundled with SDK 3.5 or later).
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:
dpm publish component --help command for more available options.
You can also view the published versions and tags of a component:
Typical Workflow
A common development cycle withdpm:
Related Pages
- Daml SDK — What the SDK includes and how versions work
- Sandbox — Local testing environment started by
dpm sandbox - Daml Studio — VS Code extension launched by
dpm studio - Daml Script — Writing and running tests with
dpm test
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, rundpm sandbox --help in your terminal:
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 namedsandbox, 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:
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
Operate
Start Canton with a single participant: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: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 runningdpm sandbox) you may connect to Sandbox remotely by running the dpm canton-console command in a separate terminal:
exit command.
Built-in documentation
The Canton console comes with built-in documentation. You can use thehelp 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:
Interact with the Sandbox
One of the objects available in the Canton console represents the Sandbox itself. The object is calledsandbox 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:
How it works
Canton offers a console where you can run administrative or debugging commands. When you run the Sandbox usingdpm 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 isolationRun with authorization
By default, Sandbox accepts all valid Ledger API requests without performing any request authorization. To start Sandbox with authorization using JWT-based 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 withdpm sandbox --config auth.conf.
auth-services are described in detail in Authorization documentation
Generate JSON web tokens (JWT)
To generate access tokens for testing purposes, use the jwt.io web site.Generate RSA keys
To generate RSA keys for testing purposes, use the following commandsandbox.key: the private key in PEM/DER/PKCS#1 formatsandbox.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 commandecdsa256.key: the private key in PEM/DER/PKCS#1 formatecdsa256.crt: a self-signed certificate containing the public key, in PEM/DER/X.509 Certificate format
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. theapplication_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.
Dev Protocol
To enable the canton dev protocol:Troubleshoot
Failed to bind to address
By default, Sandbox reserves five ports for its Canton services:6865for the participant’s Ledger API6866for the participant’s Admin API6867for the sequencer’s public API6868for the sequencer’s admin API6869for the mediator’s admin API
--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:
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:
- 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-portto change the port to which the JSON API binds.
SDK not installed
If thedaml.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:
- Install the SDK as instructed to by the error, or
- Change the SDK version in the project’s
daml.yamlfile, or - Change directories to be outside of the project, where the default Daml version that is already installed on your system will be used.