smolvm ui

Use smolvm ui to open a local browser dashboard for your sandboxes. You can inspect running sandboxes, view logs, and manage common actions without switching between terminal commands.

Synopsis

smolvm ui [OPTIONS]

Description

The ui command starts a local web server that hosts the SmolVM dashboard interface. The dashboard provides a graphical interface for managing VMs, viewing logs, and monitoring system resources.

The dashboard requires the dashboard extra to be installed: pip install 'smolvm[dashboard]'

When SmolVM runs from an installed package and the dashboard build is not already present, the server downloads the newest stable dashboard asset from GitHub Releases. Dashboard assets are named like smolvm-dashboard-ui-<tag>.tar.gz and are cached under the local SmolVM data directory.

Options

--host

string

default:"127.0.0.1"

Bind host address. Use 0.0.0.0 to allow external connections.

--port

integer

default:"8080"

Bind port (must be between 1-65535).

--allow-beta

flag

default:"false"

Allow dashboard UI downloads from prerelease/beta tags. Enables access to experimental features.

Examples

Start with default settings

Start the dashboard on localhost:8080:

smolvm ui

Output:

Starting SmolVM UI on http://127.0.0.1:8080 ...
Once started, open http://localhost:8080 in your browser.
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Use a custom port

Start the dashboard on port 3000:

smolvm ui --port 3000

Output:

Starting SmolVM UI on http://127.0.0.1:3000 ...
Once started, open http://localhost:3000 in your browser.
INFO:     Uvicorn running on http://127.0.0.1:3000 (Press CTRL+C to quit)

Allow external connections

Bind to all interfaces to allow remote access:

smolvm ui --host 0.0.0.0 --port 8080

Output:

Starting SmolVM UI on http://0.0.0.0:8080 ...
Once started, open http://localhost:8080 in your browser.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Binding to 0.0.0.0 allows connections from any network interface. Ensure appropriate firewall rules are in place.

Enable beta features

Use prerelease dashboard UI assets when you want to test dashboard changes before the next stable release:

smolvm ui --allow-beta

Output:

Starting SmolVM UI on http://127.0.0.1:8080 ...
Once started, open http://localhost:8080 in your browser.
Using prerelease dashboard UI assets (--allow-beta enabled).
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Combine options

Custom host, port, and beta features:

smolvm ui --host 0.0.0.0 --port 9000 --allow-beta

Dashboard Features

The SmolVM dashboard provides:

VM Management: Create, start, stop, and delete VMs
Real-time Monitoring: View VM status, resource usage, and logs
Network Configuration: Manage port forwarding and network settings
Console Access: Web-based terminal access to VMs
Environment Variables: GUI for managing VM environment variables

Dashboard release assets

The dashboard UI is published separately from the Python server code. At startup, smolvm ui scans recent SmolVM releases, finds the newest dashboard bundle, downloads it, and extracts the dist/ directory for static file serving. Stable releases are used by default. Pass --allow-beta to include prerelease dashboard bundles. You can override the static UI directory for local dashboard development:

SMOLVM_DASHBOARD_UI_DIST=/path/to/ui/dist smolvm ui

Environment Variables

The UI command sets the following environment variables during runtime:

SMOLVM_DASHBOARD_URL

string

Set to the dashboard URL (e.g., http://localhost:8080). Used by dashboard components.

SMOLVM_DASHBOARD_ALLOW_BETA

string

Set to "1" when --allow-beta is enabled. Triggers beta asset downloads.

These environment variables are automatically managed and restored to their previous values when the server stops.

Requirements

The dashboard requires additional dependencies. Install them with:

pip install 'smolvm[dashboard]'

This installs:

fastapi>=0.115.0 - Web framework
uvicorn[standard]>=0.34.0 - ASGI server
websockets>=14.0 - WebSocket support for real-time updates

Stopping the Server

Press Ctrl+C to stop the dashboard server gracefully:

^C
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [12345]

Exit Codes

Code	Description
`0`	Success - server started and stopped cleanly
`1`	Error - failed to start server (missing dependencies, port in use, etc.)
`2`	Invalid usage - invalid port number
`130`	Interrupted - server stopped via Ctrl+C

Common Issues

Missing dashboard dependencies

Error: Dashboard dependencies are not installed. Install with: pip install 'smolvm[dashboard]'

Solution: Install the dashboard extra:

pip install 'smolvm[dashboard]'

Port already in use

Error: failed to start UI: [Errno 98] Address already in use

Solution: Use a different port or stop the process using the current port:

smolvm ui --port 8081

Invalid port number

Error: invalid port 99999. Expected 1-65535.

Solution: Use a valid port number between 1 and 65535:

smolvm ui --port 8080

Production Deployment

For production deployments, consider:

Reverse Proxy: Use Nginx or Caddy to handle HTTPS
Authentication: Implement authentication middleware
Process Management: Use systemd or supervisord for automatic restarts
Resource Limits: Set appropriate ulimits and container limits

Example systemd service

[Unit]
Description=SmolVM Dashboard
After=network.target

[Service]
Type=simple
User=smolvm
WorkingDirectory=/home/smolvm
ExecStart=/usr/local/bin/smolvm ui --host 127.0.0.1 --port 8080
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

smolvm doctor - Verify system requirements before starting the UI
smolvm sandbox delete - Delete sandboxes managed through the dashboard
smolvm server start - Start the local HTTP API server

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Synopsis

Description

Options

Examples

Start with default settings

Use a custom port

Allow external connections

Enable beta features

Combine options

Dashboard Features

Dashboard release assets

Environment Variables

Requirements

Stopping the Server

Exit Codes

Common Issues

Missing dashboard dependencies

Port already in use

Invalid port number

Production Deployment

Example systemd service

​Synopsis

​Description

​Options

​Examples

​Start with default settings

​Use a custom port

​Allow external connections

​Enable beta features

​Combine options

​Dashboard Features

​Dashboard release assets

​Environment Variables

​Requirements

​Stopping the Server

​Exit Codes

​Common Issues

​Missing dashboard dependencies

​Port already in use

​Invalid port number

​Production Deployment

​Example systemd service

​Related Commands

Synopsis

Description

Options

Examples

Start with default settings

Use a custom port

Allow external connections

Enable beta features

Combine options

Dashboard Features

Dashboard release assets

Environment Variables

Requirements

Stopping the Server

Exit Codes

Common Issues

Missing dashboard dependencies

Port already in use

Invalid port number

Production Deployment

Example systemd service

Related Commands