Install the local tools on macOS or Linux

Browser-only recipients need an EVM wallet and the verified HTTPS site. Local signing and node operation require Docker with Compose. Host uv is optional. Start in a new directory reserved for this project. Keep downloads, keys, caches and data there. No just, jq, global Node.js, npm, Python packages or Git are needed to use a verified release archive. Do not use an unreviewed forum script as an installer.

macOS: Apple Silicon and Intel

Run uname -m in Terminal. arm64 means Apple Silicon; x86_64 means Intel. Download the corresponding installer from the official Docker Desktop for Mac page. Open the DMG, drag Docker to Applications, start Docker, and complete its setup. Docker documents at least 4 GiB of host RAM for Desktop. Our node container cap is 512 MiB; Desktop, the host OS and image builds are additional. A measured image build peak is not yet recorded. Review Docker's licensing terms for your organization.

The native Terminal tools provide curl, tar, shasum, awk, bash, id, mkdir and chmod. Homebrew and GNU coreutils are optional. This guide uses neither readlink -f, GNU sed -i, GNU date, nor host timeout. On Apple Silicon, images must support linux/arm64; do not silently force amd64 emulation for a validator. Docker image availability is checked below. Native macOS runtime validation remains a release evidence gap until tested on actual Macs.

Linux: Ubuntu 24.04 or 22.04, amd64 or arm64

On a clean supported Ubuntu host, install Docker Engine and the Compose plugin using Docker's signed repository. These commands install host packages and require your machine administrator's authorization. If Docker is already in use, follow Docker's upgrade/conflict instructions instead of replacing it blindly. The official Ubuntu instructions are authoritative for supported versions and repository changes.

sudo apt-get update
sudo apt-get install -y ca-certificates curl bash tar coreutils mawk
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl --fail --silent --show-error https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
. /etc/os-release
tokn_arch=$(dpkg --print-architecture)
tokn_suite=${UBUNTU_CODENAME:-$VERSION_CODENAME}
echo "deb [arch=$tokn_arch signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $tokn_suite stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Arrange Docker access for your account using your administrator's policy or Docker rootless mode. The later commands expect docker info to work without sudo; do not run a wallet wrapper as root merely to bypass permissions. Docker-group access grants control over the host. Other distributions use their matching Docker installation guide; the Ubuntu repository commands above must not be copied to a different distribution.

Default: verify first, then use Docker only

Read the 60-second trust check, download the published archive and checksums, and verify them with your operating system's SHA-256 tool before executing project code. Inspect the selected Compose file and its exact image references as text. The minimal participant kit has its own preflight and command reference; its wallet-only path is the default for the published v3.1.14 release. The release index identifies the actual production wallet kit and the separate TEST wallet/operator downloads. The preserved v2.0.0 full-source reference does not contain the minimal kit.

After static inspection, check Docker without creating keys or making a payment:

docker version
docker compose version
docker info --format '{{.OSType}}/{{.Architecture}}'

The selected image's manifest must include your architecture. Inspect exact digest references from the checked Compose file, not a mutable image tag. The participant preflight checks this selection and reports runtime privileges, mounts and ports. Image builds and pulls need HTTPS, working DNS and free disk space. No host uv, just, jq, Node.js, npm, or Python package installation is needed for that path.

For a pure Python inspection or test, the pinned uv container is an alternative to host uv. First explicitly pull the exact uv image listed in the verified kit README. This example runs only the interpreter version check, has no network, no Docker socket, no project bind mount and no persistent output:

docker run --rm --pull=never --network none --read-only --tmpfs /tmp:size=8m --user 65534:65534 \
  ghcr.io/astral-sh/uv:0.11.16-python3.12-trixie-slim@sha256:438bad5bb636f6cc60765ed25f294c74dd896e6d14b2093c3467a37b5d03a78a \
  uv run --no-project --no-config --no-cache --no-python-downloads python -c 'import sys; print(sys.version.split()[0])'

Do not mount docker.sock into that image to run a Python Docker wrapper. Use direct Compose wallet commands instead. A full node additionally needs an agreed P2P endpoint, firewall/NAT configuration and an accurate clock. A synchronized private node alone cannot satisfy the external-node gate.

Verify and use the release

Continue with getting started. Its default wallet commands use the published v3.1.14 kit; its v2.0.0 full-source example is an immutable reference. The TEST TOKN pilot also has published wallet/operator downloads and verified services; the independent external pilot remains incomplete. On macOS use shasum -a 256 -c SHA256SUMS; Linux can use sha256sum -c SHA256SUMS. The start guide detects the available command. Both platforms use tar -xzf after verification. Never merge a fresh extraction into an existing chain, wallet or node-data directory.

just recipes are optional shortcuts. You can inspect justfile without running it; if you install just using its official instructions, the following mappings are exact after entering the extracted project:

Additional arguments follow the same direct command: for example replace status with create my-wallet. Only explicitly chosen signing actions (transfers, work/review/staking, address claims and cohort consent or attestations) request signatures. A connection or status query does not transfer funds.

Tools needed only by maintainers

Git is needed only for source development. SSH and rsync are needed only for an authorized remote deployment; that Linux host also needs uv, Python 3.12 and Docker. Node.js/npm are needed on the host only for the optional Cloudflare maintainer CLI; the deployment guide identifies that path. openssl, jq, GNU sed/readlink/date, and host coreutils extensions are not participant prerequisites. Backup encryption runs inside the Node toolbox. Four-node QA requires more memory than one peer and does not establish external operator independence.

Optional host uv for maintainers

In your chosen project download directory, install the pinned uv binary locally. The installer is downloaded for inspection before execution. Its URL belongs to Astral, not the forum or this project's server. Read the uv installation instructions and installer options if your organization uses a managed package source.

mkdir -p .tools .cache/tmp
curl --fail --silent --show-error --max-time 60 https://astral.sh/uv/0.11.16/install.sh -o .tools/uv-install.sh
UV_UNMANAGED_INSTALL="$PWD/.tools" sh .tools/uv-install.sh
export PATH="$PWD/.tools:$PATH"
export UV_CACHE_DIR="$PWD/.cache/uv"
export UV_PYTHON_INSTALL_DIR="$PWD/.cache/uv-python"
export UV_PYTHON_BIN_DIR="$PWD/.tools"
export UV_TOOL_DIR="$PWD/.cache/uv-tools"
export UV_TOOL_BIN_DIR="$PWD/.tools"
export TMPDIR="$PWD/.cache/tmp"
uv --version
uv python install 3.12
uv run --no-project --no-config --no-cache --python 3.12 python -c 'import sys; print(sys.version.split()[0])'
docker version
docker compose version
docker info --format '{{.OSType}}/{{.Architecture}}'

Inspect the saved installer with your trusted text editor before its separate execution command. This optional tool installation is not required for a wallet. Keep the exported paths for this terminal session. After opening a new terminal, repeat the exports from the same directory. After extracting and entering tokn/, the absolute paths still point into the project download directory. Python runs only through uv or uvx. Do not create a project .venv, use venv/virtualenv, pip install, or Poetry.