Starting and connecting

How the console fits

  • Transport: local TCP, plain-text commands, JSON responses.

  • Intended scope: development / debugging, not a production control plane.

  • Security model: binds to localhost by default; plain-text protocol (keep the port private, localhost or a private subnet only).

  • Independent of the UI: the console talks to the backend over its own TCP socket, not gRPC/gRPC-Web, you can run it with or without Weights Studio UI open, and both can be attached at once.

Start the server

From your training script (recommended), starts the server; a client REPL window opens automatically:

import weightslab as wl

wl.serve(serving_grpc=True, serving_cli=True)   # serving_cli defaults to True
wl.keep_serving()

To start the server headless (no REPL window pops up; attach later on demand), pass spawn_cli_client=False, see the serve entry in User Functions Reference:

wl.serve(serving_cli=True, spawn_cli_client=False)

Low-level equivalents (rarely needed directly, wl.serve/weightslab cli cover the normal workflow):

python -m weightslab.backend.cli serve --host localhost --port 60000
python -m weightslab.backend.cli client --host localhost --port 60000

If no port is given (or port is 0), the server picks a free port and advertises it for auto-discovery.

Attach a client

From any other terminal:

weightslab cli               # auto-discover the port
weightslab cli --port 60000  # or specify one
weightslab cli --host HOST --port PORT

Auto-discovery reads whatever port the server advertised on startup, so a bare weightslab cli is normally all you need on the same machine. Pass --host/--port explicitly when the backend is on another machine (see Ports and remote access for bridging a remote experiment) or when several experiments are running locally at once and auto-discovery would be ambiguous.

Once attached, type help (or h / ?) inside the console at any time, it prints the same reference as Console commands, with extra examples pulled from the running experiment’s own registrations.

Ending a session

  • exit / quit, close the client connection (handled server-side; the server replies, then closes the socket).

  • clear / cls, clear the local terminal screen. Handled entirely by the client, not sent to the server.

  • Ctrl+C in the server’s own terminal stops training and every service wl.serve() started, including the CLI server, the console can’t be attached to after that.

Developer notes

  • Prefer the console for quick diagnosis and manual interventions; use Weights Studio for richer visual workflows.

  • Keep the CLI port private (localhost, or a private subnet at most), the protocol is plain text with no authentication.

  • Editing hyperparameters is the only supported mutation path for architecture-level state; there is currently no console command to freeze/unfreeze layers or resize a model (that lives in the Experiment Agent Assistant and Weights Studio surfaces, and in the Python API).