Skip To Content

Getting Started

Install the server and connect a .NET client.

0.1.0-preview.10 Preview
View source on GitHub

This guide walks through running a squirix server and connecting a .NET client.

Prerequisites:

  • .NET 10 SDK (version pinned in global.json)
  • For local HTTPS (tests, benchmarks, examples; not Docker): dotnet dev-certs https --trust

1. Run a development server

NuGet global tool

dotnet tool install --global squirix.server.tool --version 0.1.0-preview.10
squirix-server run

The host listens on https://localhost:5001 by default (loopback bind), runs as an in-memory cache, and prints ready-to-use client and operational endpoint URLs. No JWT is required on this default URL — any local process can access the cache API. This is a development convenience, not production hardening. See server-mode.md — Loopback development default.

For journal/snapshot durability:

squirix-server run --persist --data-dir data

Health probes use the same HTTPS listener (local tool default port 5001):

curl https://localhost:5001/health
curl https://localhost:5001/metrics

/metrics is anonymous on loopback when auth is not configured.

If the CLI cannot bind to port 5001 or the client reports a TLS chain error such as PartialChain, check that the CLI started successfully and that the endpoint belongs to it. Another server using the port may present a different certificate. If 5001 is occupied, run squirix-server run --urls https://localhost:5443 if 5443 is free, then use the same URL for probes and the client. Keep TLS verification enabled.

Docker (fastest if you have Docker Desktop)

Development only. Examples below use the public test JWT key ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= and bundled dev HTTPS/mTLS certificates. Do not reuse them outside a local machine. See containerization.md.

Single-container examples start in the default ephemeral mode (in-memory cache). The three-node docker compose example enables persistence with --persist --data-dir /data and named volumes.

docker build -f docker/Dockerfile -t squirix-server .
docker run --rm \
  -p 5000:5000 \
  -e SQUIRIX_JWT_SIGNING_KEY=ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= \
  -e SQUIRIX_JWT_ISSUER=https://squirix.docker.dev \
  -e SQUIRIX_JWT_AUDIENCE=squirix \
  squirix-server run --urls https://0.0.0.0:5000

Port 5000 is the primary HTTPS listener (gRPC, /health, /metrics). Images ship a bundled development HTTPS certificate; use curl -k from the host. When JWT is configured, pass a bearer token for /metrics scrapes from outside the container.

Release image (NuGet tool; Dockerfile default SQUIRIX_VERSION matches the published package):

docker build -f docker/Dockerfile.release -t squirix-server:release .
docker run --rm \
  -p 5000:5000 \
  -e SQUIRIX_JWT_SIGNING_KEY=ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= \
  -e SQUIRIX_JWT_ISSUER=https://squirix.docker.dev \
  -e SQUIRIX_JWT_AUDIENCE=squirix \
  squirix-server:release run --urls https://0.0.0.0:5000

Three-node cluster (docker compose up -d in docker/): nodes A, B, and C are available at https://localhost:5001, https://localhost:5002, and https://localhost:5003. Each host port maps to container port 5000. See containerization.md.

From this repository

dotnet run --project src/squirix.server.host/Squirix.Server.Host.csproj -- run

2. Add the client SDK

dotnet add package squirix --version 0.1.0-preview.10

3. Connect and use a typed cache

Use the HTTPS gRPC endpoint from the host output.

Local tool or dotnet run (default https://localhost:5001, no JWT unless you configure auth):

using System;
using System.Threading;
using Squirix.Client;

var cancellationToken = CancellationToken.None;

await using var client = await SquirixClient.ConnectAsync(new Uri("https://localhost:5001"), cancellationToken);

var cache = await client.GetCacheAsync<string>("demo", cancellationToken);
await cache.SetAsync("greeting", "hello", cancellationToken: cancellationToken);

var lookup = await cache.GetValueAsync("greeting", cancellationToken);
Console.WriteLine(lookup.Found ? lookup.Value : "<missing>");

Expected output: hello.

Docker (JWT env vars in the examples): single-container https://localhost:5000; Compose node A https://localhost:5001. Use options.BearerTokenProvider with a JWT signed by the docker dev key and trust the container's HTTPS certificate on the client machine (see containerization.md).

using System;
using System.Threading.Tasks;
using Squirix.Client;

await using var client = await SquirixClient.ConnectAsync(
    options =>
    {
        options.Endpoints.Add(new Uri("https://localhost:5000")); // or :5001 for Compose node A
        options.BearerTokenProvider = _ => new ValueTask<string>(yourJwtBearerToken);
    },
    cancellationToken);

Multiple bootstrap endpoints (HA front door, not shards):

using System;
using Squirix.Client;

await using var client = await SquirixClient.ConnectAsync(
    options =>
    {
        options.Endpoints.Add(new Uri("https://cache-a.example.internal:5001"));
        options.Endpoints.Add(new Uri("https://cache-b.example.internal:5002"));
    },
    cancellationToken);

See bootstrap client failover and configuration.

CLI reference

squirix-server init [--settings ./Squirix.settings.json]
squirix-server validate-config --settings ./Squirix.settings.json [--strict]
squirix-server doctor [--settings ./Squirix.settings.json] [--strict]
squirix-server version

The 0.1.0-preview.10 tool package reports 0.1.0-preview.9 from the version command. Check the installed package version with dotnet tool list --global.

run accepts --urls, --persist, --data-dir (with --persist), --settings, and --strict. Without --settings, the host discovers Squirix.settings.json or squirix.settings.json in the working directory and application directory.

Next steps