Skip to content

Quick Start

Prerequisites

The runtime requires Node.js 18 or newer and Git. Docker users need Docker Engine 20.10 or newer and Docker Compose V2. Check the Node installation before starting:

node --version
npm --version

Supported repository setup

These are the supported checkout and build commands:

git clone https://git.carpocratian.org/sibyl/hypertoken.git
cd hypertoken
npm install
npm run build

npm run build cleans and compiles the TypeScript distribution, then copies the shipped example assets needed by the package.

Supported example commands

Run these from the repository root. npm run blackjack uses the built Blackjack CLI; the other commands use the repository's example scripts and browser tooling.

npm run blackjack
npm run cuttle
npm run watershed:web

npm run watershed:web builds the browser bundle and starts a Python HTTP server on port 8080. It is a long-running command. npm run blackjack is interactive; npm run cuttle starts the Cuttle CLI.

Supported relay command

The relay is a message-forwarding service used by peer clients:

npm run relay

The default relay configuration listens on port 3000. The relay is unauthenticated; do not treat it as an authorization boundary.

Supported Docker commands

Build the image and run the relay with Docker Compose:

docker build -t hypertoken:latest .
docker compose up relay

The Compose file also defines the optional example profile:

docker compose --profile examples up
docker compose up blackjack-server
docker compose run blackjack-alice
docker compose run blackjack-bob

The relay maps port 3000. The example Blackjack server maps port 9090. These commands use the services defined in docker-compose.yml; they are not a generic deployment configuration.

Build the documentation locally

Install the documentation dependencies from the repository root, then serve or build the MkDocs site:

python3 -m pip install -r requirements-docs.txt
python3 -m mkdocs serve
python3 -m mkdocs build --strict

serve starts a local development server. build --strict writes the static site to site/ and treats warnings as errors.

Where to go next

  • Read CRDT State to understand the document model.
  • Read Actions before adding gameplay state changes.
  • Read System Overview for the integration path.
  • Run npm run test:quick for the repository's custom test runner; npm run test:unit covers the core, engine, and exporters.