Standalone Deployment

Run Swytch as a local process, container, or standalone server when Kubernetes sidecars are not the right fit. For Kubernetes, start with the operator.

Install the binary from Swytch releases, or use ghcr.io/swytchdb/swytch:latest for local evaluation. Pin a release image for production.

The simplest deployment runs one Swytch instance as an in-memory cache:

swytch redis --maxmemory=4gb --bind=0.0.0.0 --metrics-port=9090

For applications on the same host, a unix socket avoids TCP overhead entirely:

swytch redis --maxmemory=4gb --unixsocket=/var/run/swytch.sock --bind=""

Add a dedicated data directory to mirror resident effects:

swytch redis --bind=127.0.0.1 --maxmemory=4gb --data-dir=/var/lib/swytch

Reuse that directory on restart and mount persistent storage there when running in a container. Each process needs its own directory. Syncs are asynchronous, and eviction removes unreferenced effects from the mirror.

If recovery runs out of its memory budget, Swytch waits 30 seconds before deleting the mirror and starting empty. Stop it during that window to preserve the files and restart with more memory. The local durability guide covers setup, sync timing, and the full recovery procedure.

Swytch supports native TLS for client connections:

# TLS (server certificate only)
swytch redis --tls-cert-file=server.crt --tls-key-file=server.key

# mTLS (require client certificates)
swytch redis \
  --tls-cert-file=server.crt \
  --tls-key-file=server.key \
  --tls-ca-cert-file=ca.crt

Both --tls-cert-file and --tls-key-file must be provided together. Adding --tls-ca-cert-file enables mutual TLS where clients must present a certificate signed by the given CA.

The minimum TLS version defaults to 1.2. Override with --tls-min-version=1.3 if required.

Connect with redis-cli over TLS:

redis-cli --tls --cert client.crt --key client.key --cacert ca.crt

Swytch nodes form a leaderless cluster over QUIC+mTLS. Every node accepts reads and writes. No leader election, no quorum configuration.

Generate a shared passphrase. This is the sole trust root for the cluster:

swytch gen-passphrase
# outputs: YUa6WXJDsloKgx4BQWV2edOiH3U2Ym4O5VLR1jrVvO4

All nodes in the cluster must use the same passphrase. Each node derives a shared CA from it and generates ephemeral leaf certificates on startup. No manual certificate distribution is needed.

Use --join ip:port to contact a cluster peer and --cluster-advertise ip:port to publish this node’s own reachable address. Use the QUIC cluster port for both. In this example, the hosts are 10.0.0.1 and 10.0.0.2:

# Node 1: start the first node using its own address as the seed
swytch redis --bind=0.0.0.0 --cluster-passphrase="YUa6..." \
  --cluster-port 7379 \
  --cluster-advertise 10.0.0.1:7379 \
  --join 10.0.0.1:7379

# Node 2: join the running first node and advertise this host's address
swytch redis --bind=0.0.0.0 --cluster-passphrase="YUa6..." \
  --cluster-port 7379 \
  --cluster-advertise 10.0.0.2:7379 \
  --join 10.0.0.1:7379

Replace the example IPs and passphrase with your own. Start node 1 before node 2. Allow UDP 7379 between their advertised addresses. Nodes connect over QUIC and share data through subscriptions.

The join address is a bootstrap contact. Once joined, a node learns the other peers and their advertised addresses through membership effects. Additional nodes can join any reachable member using the same passphrase.

You can supply several bootstrap contacts as a comma-separated list:

swytch redis --bind=0.0.0.0 --cluster-passphrase="YUa6..." \
  --cluster-port 7379 \
  --cluster-advertise 10.0.0.3:7379 \
  --join 10.0.0.1:7379,10.0.0.2:7379

By default the cluster port is the Redis port + 1000 (e.g., port 6379 uses cluster port 7379). Override with --cluster-port.

Set --cluster-advertise ip:port to the address other nodes can use to reach this specific node. Behind NAT, use its reachable address and forwarded UDP port. The advertised endpoint must route to that node’s --cluster-port listener. Use a distinct endpoint for each node. For multiple nodes on one machine, assign distinct Redis and cluster ports; use 127.0.0.1 only when all peers are on that machine.

Membership is not a special subsystem — it uses the same effects engine as all other data. Each node periodically writes a heartbeat effect on an internal key. Crashed nodes expire after 30 seconds. Graceful shutdowns remove the entry immediately.

Inspect membership from any Redis client:

redis-cli HGETALL __swytch:members

This two-node example assigns fixed container IPs on a dedicated network. Choose a subnet that does not overlap your existing networks, and set CLUSTER_PASSPHRASE to the shared secret before starting it.

services:
  cache1:
    image: ghcr.io/swytchdb/swytch:latest
    command: >
      redis
        --bind 0.0.0.0
        --maxmemory 1gb
        --cluster-passphrase ${CLUSTER_PASSPHRASE}
        --cluster-port 7379
        --cluster-advertise 172.28.0.11:7379
        --join 172.28.0.11:7379
        --metrics-port 9090
    ports:
      - "127.0.0.1:6379:6379"
      - "127.0.0.1:9090:9090"
    networks:
      swytch:
        ipv4_address: 172.28.0.11

  cache2:
    image: ghcr.io/swytchdb/swytch:latest
    command: >
      redis
        --bind 0.0.0.0
        --maxmemory 1gb
        --cluster-passphrase ${CLUSTER_PASSPHRASE}
        --cluster-port 7379
        --cluster-advertise 172.28.0.12:7379
        --join 172.28.0.11:7379
        --metrics-port 9090
    ports:
      - "127.0.0.1:6380:6379"
      - "127.0.0.1:9091:9090"
    networks:
      swytch:
        ipv4_address: 172.28.0.12

networks:
  swytch:
    ipam:
      config:
        - subnet: 172.28.0.0/24

Save this as compose.yaml. Start cache1 with docker compose up -d cache1, wait for redis-cli -p 6379 PING to return PONG, then start cache2 with docker compose up -d cache2. Redis clients on the host connect to ports 6379 and 6380; cluster traffic uses the advertised container IPs on UDP 7379. Stop the example with docker compose down.

On an image with --data-dir support, add --data-dir /data to each service’s command and give each service a different named volume. Merge these mounts and top-level volume declarations into the existing example:

services:
  cache1:
    volumes:
      - cache1-data:/data
  cache2:
    volumes:
      - cache2-data:/data
volumes:
  cache1-data:
  cache2-data:

Each service keeps its existing --join and --cluster-advertise settings. docker compose down retains named volumes; docker compose down -v deletes them. Recovery still needs enough memory and does not load a complete copy of every cluster key. See local durability.

Use the operator quickstart to attach a sidecar or create a server Deployment. The operator manages peer discovery and injection from a Swytch resource.

Configure Swytch Cloud when acknowledged state must remain available beyond local working sets or disks. It can be used alongside --data-dir. Uploads and local file syncs are separate asynchronous operations; read their durability boundaries before planning a restart.

When --metrics-port is set, Swytch exposes:

Swytch handles POSIX signals for graceful shutdown:

For container orchestration, send SIGTERM to stop the server gracefully. There is no drain period configuration; shutdown completes as fast as pending work allows.

With --data-dir, clean shutdown also flushes pending mirror records. Allow storage I/O to finish before forcing a kill.

Set the container memory limit higher than --maxmemory to account for connection buffers, Lua scripting overhead, and Go runtime:

container_memory = maxmemory + max(512MB, maxmemory * 0.2)

Treat this as an initial allowance, then measure your workload. With --data-dir, also measure recovery memory and mapped file pages before choosing a limit. See local durability capacity.

Swytch uses all available CPUs by default (--threads=0). Override with --threads=N to limit.

See the Sizing and Capacity Planning guide for detailed memory estimation and scaling guidance.