CLI Reference

The runsight command starts the Runsight server (FastAPI + Uvicorn). The CLI is intentionally minimal — it launches the server and serves the bundled GUI.

Running with uvx

The recommended way to run Runsight is via uvx, which handles Python package resolution automatically:

uvx runsight

This installs the runsight package (if not already cached) and runs the runsight entry point, which is registered in pyproject.toml as:

[project.scripts]
runsight = "runsight_api.cli:main"

Command syntax

runsight [--host HOST] [--port PORT]

Options

Flag	Type	Default	Description
--host	str	127.0.0.1	Bind address for the server
--port	int	8000	Bind port for the server
--help, -h	—	—	Print usage information and exit

Unknown arguments cause the CLI to print an error and exit with code 1.

Examples

# Start with defaults (127.0.0.1:8000)
uvx runsight

# Custom port
uvx runsight --port 3000

# Bind to localhost only
uvx runsight --host 127.0.0.1 --port 9000

# Bind to all interfaces only when protected by your own network and auth controls
uvx runsight --host 0.0.0.0 --port 8000

On startup, the CLI prints:

  Runsight running at http://localhost:8000
  Press Ctrl+C to stop

Docker

Runsight ships a multi-stage Dockerfile that bundles the frontend and backend into a single image.

# Build the image
docker build -t runsight .

# Run for local-only access
docker run -p 127.0.0.1:8000:8000 runsight

# Mount the whole workspace root so .runsight state persists too
docker run -p 127.0.0.1:8000:8000 -v "$(pwd)":/workspace runsight

Environment variables

Variable	Default	Description
RUNSIGHT_BASE_PATH	/workspace	Root path for workflow discovery
RUNSIGHT_STATIC_DIR	/app/static	Path to the bundled frontend assets
RUNSIGHT_LOG_FORMAT	text	Log output format

The container exposes port 8000 and includes a health check at /health.

Caution

Publishing the container on a non-loopback interface exposes an unauthenticated API unless you add your own proxy or authentication controls.

Passing CLI flags in Docker

The default Docker CMD is ["runsight"]. Override it to pass flags:

docker run -p 127.0.0.1:3000:3000 runsight runsight --host 0.0.0.0 --port 3000

Requirements

• Python >= 3.11
• The runsight package installs FastAPI, Uvicorn, SQLModel, and all other dependencies automatically.