Installation

Homepage · Architecture · Developer integration

Install the server

On Debian Trixie, install the base requirements and run the installer from a release checkout:

sudo apt install python3-venv mariadb-server openssl
sudo scripts/install.sh

The installer creates /opt/prod/snakelab, provisions the database, builds the Python environment, and starts snake-lab.service. The environment always uses the CPU PyTorch runtime.

systemctl status snake-lab.service
journalctl -u snake-lab.service -f
tail -f /opt/prod/snakelab/logs/server.log

Simulation, policy inference, and training run on CPU, including on hosts with an NVIDIA GPU. No NVIDIA driver or CUDA toolkit is required.

Network configuration

DSnakeLab.CMDB_NETWORK is the single source of listener defaults:

Use	Bind interface	TCP port
control	0.0.0.0	41970
telemetry	0.0.0.0	41971
events	0.0.0.0	41972

Installation creates /opt/prod/snakelab/conf/snakelab.json from the declaration when missing. Upgrade preserves existing settings and validates them before stopping the service. A missing file uses defaults; partial settings inherit omitted uses and fields. For example:

{
  "network": {
    "control": {"interface": "127.0.0.1", "port": 42970}
  }
}

Only known uses, interface (an IPv4 address), and port (an integer 1–65535) are accepted. Invalid files fail with the file path and setting in the error. No credentials belong in this file.

After editing, validate and restart with:

sudo /opt/prod/snakelab/scripts/restart.sh

Each process reads configuration once. Restart clients and benchmark processes to pick up edits too. Local clients use the configured destination for each listener, translating 0.0.0.0 into 127.0.0.1. Remote clients need their local configuration or explicit CLI arguments matching the server’s ports.

Server --address, --port, --telemetry-port, and --events-port override resolved defaults for that invocation; --address applies to all three listeners. Client --host, --control-port, and --telemetry-port override client destinations; --host applies to both client connections. Database connection settings remain separate from listener configuration. See CMDB_NETWORK for the declaration standard and CMDB metadata for all supported declarations.

Start the client

lab-client

Connect to another trusted host with lab-client --host SERVER. See Run a simulation for submitting configurations and controlling runs.

The Configuration panel reads the nine LLM-tuned values for the current run from MariaDB using a read-only transaction. It excludes fixed settings. Database access is separate from ZMQ; use a credentials JSON file readable by the client user, containing password and optionally user and database:

client/lab-client.sh --host SERVER --db-host DATABASE_HOST --db-credentials /path/to/database.json

Defaults use the existing local Snake Lab database settings. If the database is unavailable, telemetry continues and the panel reports configuration as unavailable. The client does not initialize, migrate, or update the database.

Back up the database

Back up the local database with sudo scripts/backup-db.sh. The SQL dump is saved in the current directory as YYYY-MM-DD_HH:MM-snakelab-db.dump, using local time. An existing backup from the same minute is never overwritten.

Benchmark

Run a benchmark against an idle local server from this checkout:

sudo scripts/run-benchmark.py -c examples/sample-config.json

The script automatically uses the installed virtual environment at /opt/prod/snakelab/venv, deriving the install directory from the credential path in DSnakeLab.DB_CREDENTIALS_FILE. The tool uses the installed credentials at /opt/prod/snakelab/config/database.json, prints Snake Lab Benchmark: XXX steps per second, and calculates throughput using the run’s database start and completion timestamps (including simulation setup and persistence). Add -v for episode progress, timing, and cleanup details. Before printing the final result, it deletes only that run and its cascading episode and configuration records. Failed or interrupted runs are retained, with their run ID printed for inspection; interrupting the tool does not cancel the simulation.

See Development setup to run from a source checkout.

Upgrade

Do not upgrade while a simulation is running. From the new release checkout:

sudo scripts/upgrade.sh

The upgrade script stops the service, applies database schemas v1–v5, deploys the software, and restarts the service. It rebuilds the virtual environment when requirements change or the installation moves, and does not provision MariaDB.

Existing /opt/snake-lab installations are moved to /opt/prod/snakelab. Credentials and logs move with the installation; the database name, account, and stored results stay the same. The virtual environment is rebuilt because its launchers contain absolute paths. If rebuilding fails, the service stays stopped; fix the reported error and rerun the upgrade. The script refuses to migrate when both installation directories already exist.

CMDB discovery

Register SnakeLab using CMDB’s Add Application, then run Re-Scan Applications on the inventoried host. CMDB reads the literal version from /opt/prod/snakelab/snakelab/constants/DSnakeLab.py and records the installed release and host deployment. The name must be exactly SnakeLab; names with spaces or hyphens do not meet CMDB’s discovery convention. Development checkouts under /opt/dev are not discovery targets.

Python entry points are now python -m snakelab.server and python -m snakelab.client; shared constants are in snakelab.constants.

Fresh installations apply the same schemas. To apply them separately while the service is stopped, use sudo scripts/apply-database-schema.sh. Schema application is safe to repeat; it does not backfill historical configuration rows or high-score snapshots. See Configuration queries for storage details and migration context.

Uninstall

sudo scripts/uninstall.sh

The uninstaller removes the service, /opt/prod/snakelab, and the configured MariaDB database, including all simulation history. The MariaDB user remains.