---
title: "Setup"
description: "Learn how to install and run the open-source version of the walt.id Wallet API v2."
stack: "Community Stack (open source) — version 1.1.1"
stack_version: "1.1.1"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet2/setup
generated: 2026-10-01
---
# Setup

## Installation & Running the Project

Make sure you have Docker installed on your machine.

**Note:**

Want to see the whole flow — issue a credential, receive it into the wallet, and present it? The [Docker Compose quick start](https://docs.walt.id/community-stack/home.md#quick-start) spins up the Issuer, Verifier, and Wallet together in one command. This page covers running the Wallet API v2 on its own.

### Option 1: Using Docker Pull

**1. Clone the Identity Repo**

Clone the repository to your local machine. The repo contains the default configuration files that will be mounted into the container in the next step.

```bash
git clone https://github.com/walt-id/waltid-identity.git && cd waltid-identity
```

**2. Pull the Docker Image**

Pull the pre-built Docker image from Docker Hub:

```bash
docker pull waltid/wallet-api2
```

**3. Run the Docker Image**

Run the container, mounting the config directory from the cloned repository. This gives the service its default configuration — see the note below for details.

```bash
docker run -p 7006:7006 \
  -itv $(pwd)/waltid-services/waltid-wallet-api2/config:/waltid-wallet-api2/config \
  -t waltid/wallet-api2
```

The `-v` flag mounts `waltid-services/waltid-wallet-api2/config` from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, persistence, authentication). You can edit these files before starting the container to customize the service behavior.

**Note:**

See the [configuration reference](https://docs.walt.id/community-stack/wallet2/configurations/feature-manager.md) for a full description of all available config files and their fields. The shipped config enables **SQLite persistence** and leaves **authentication off** unless you enable and configure the `auth` feature.

Once the container starts, the API is available at `http://localhost:7006`. You can confirm it is running by opening `http://localhost:7006/swagger` in your browser.

### Option 2: Building the Image Yourself

**Note:**

This option requires **Java (JDK 17+)**, **Gradle**, and **Docker** to be installed on your machine.

**1. Clone the Identity Repo**

Clone the repository to your local machine:

```bash
git clone https://github.com/walt-id/waltid-identity.git && cd waltid-identity
```

**2. Build the Docker Image**

If you prefer to build the Docker image yourself, use the Gradle Ktor/Jib tasks:

```bash
# Development (local Docker daemon, single-arch)
./gradlew :waltid-services:waltid-wallet-api2:publishImageToLocalRegistry
# image: waltid/wallet-api2:{version}
```

```bash
# Production (multi-arch push to your registry)
export DOCKER_USERNAME={your-dockerhub-namespace}
export DOCKER_PASSWORD={your-dockerhub-token}
./gradlew :waltid-services:waltid-wallet-api2:publishImage
# image: docker.io/{DOCKER_USERNAME}/wallet-api2:{version}
```

**3. Run the Docker Image**

After building the image, run it using (adjust the image name if you pushed to your registry):

```bash
docker run -p 7006:7006 \
  -itv $(pwd)/waltid-services/waltid-wallet-api2/config:/waltid-wallet-api2/config \
  -t waltid/wallet-api2
```

The `-v` flag mounts `waltid-services/waltid-wallet-api2/config` from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, persistence, authentication). You can edit these files before starting the container to customize the service behavior.

**Note:**

See the [configuration reference](https://docs.walt.id/community-stack/wallet2/configurations/feature-manager.md) for a full description of all available config files and their fields.

Once the container starts, the API is available at `http://localhost:7006`. You can confirm it is running by opening `http://localhost:7006/swagger` in your browser.

**Note:**

The Wallet API v2 listens on port `7006` by default — the same whether run standalone or via [Docker Compose](https://docs.walt.id/community-stack/home.md#quick-start) alongside the other services. Issuer2 defaults to `7005` and Verifier2 to `7004`.

## Start Using the Wallet

Now that the Wallet API v2 is running, create a wallet and put it to work:

1. [Create your first wallet](https://docs.walt.id/community-stack/wallet2/wallets.md) — Every operation is scoped to a wallet; start here to get a `walletId`.
2. [Manage keys](https://docs.walt.id/community-stack/wallet2/key-management/overview.md) & [DIDs](https://docs.walt.id/community-stack/wallet2/did-management.md) — The identity material the wallet signs with.
3. [Receive a credential](https://docs.walt.id/community-stack/wallet2/credential-receiving/sd-jwt-vc.md) — Claim what an issuer offers over OID4VCI.
4. [Present a credential](https://docs.walt.id/community-stack/wallet2/credential-presenting/sd-jwt-vc.md) — Share it with a verifier over OID4VP.
5. [Full API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md) — Explore all available endpoints via Swagger.