Server and Fleet Setup

Status: Current Last updated: 2026-08-30 19:35 EDT

Overview

Batchalign3 can run as a persistent server that accepts jobs from remote clients. This is useful when multiple people share one powerful machine, when you want warm workers to survive across commands, or when audio files live on a central server instead of on each laptop.

Architecture

┌───────────────────────────────────────┐
│  Server machine (GPU, lots of RAM)    │
│                                       │
│  ┌───────────────────────────────┐    │
│  │ batchalign3 server (port 8001)│    │
│  └───────────────────────────────┘    │
│                  │                    │
│             Python workers            │
│          (Stanza, Whisper, etc.)      │
└───────────────────────────────────────┘
         ▲                ▲
    Laptop A          Desktop B
    --server URL      --server URL

Clients use --server http://server:8001 to send work. The server dispatches to Python workers, manages job lifecycle, and returns results.

Single-machine server

1. Install batchalign3 on the server

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/FranklinChen/talkbank-tools/releases/latest/download/install-batchalign3.sh | sh

2. Configure batchalign3

Create ~/.batchalign3/server.yaml:

port: 8001
host: "0.0.0.0"
max_concurrent_jobs: 4

# Map data repository names to media file locations.
media_mappings:
  my-corpus: /path/to/audio/files
  another-corpus: /path/to/more/audio

3. Start the server

batchalign3 serve start --port 8001 --host 0.0.0.0 -v

4. Connect from clients

On any machine that can reach the server:

batchalign3 --server http://server:8001 morphotag corpus/ -o output/
batchalign3 --server http://server:8001 align corpus/ -o output/

Shared media via NFS or mounted storage

For audio commands (align, transcribe), the execution host must be able to read the media files.

Recommended approach:

1. Export or mount the media directories on the server at a canonical path.
2. Configure media_mappings so corpus-relative roots resolve to that mounted storage.
3. Run remote submissions against the server that can already see those paths.

Server management

# Check server status
batchalign3 serve status

# Stop the server
batchalign3 serve stop

# View server health
curl http://localhost:8001/health | python3 -m json.tool

After the server has run a Python-hosted task, the health response includes one entry in worker_runtime_identities. These path-free SHA-256 values identify the interpreter, installed Batchalign code, and installed distribution inventory that actually executed worker requests. An empty list means no current-protocol local Python worker has been observed since server startup; it does not mean the server guessed the identity from whichever python is on your shell path. A second worker with different code is refused before it can run a job, so the field never presents several possible producers. The package digest covers executable package source, native modules, and data; generated bytecode, hidden scratch, and the package’s test subtree are excluded so parallel test-runner bookkeeping cannot masquerade as a runtime change.

curl -s http://localhost:8001/health | \
  python3 -c 'import json,sys; print(json.load(sys.stdin)["worker_runtime_identities"])'

Direct mode vs server mode

Most users should start with direct mode. Server mode is for teams managing shared infrastructure.

This page last changed: 2026-09-10 (commit 423245db). The whole book last changed: 2026-09-16 (commit 34d249d8).