Dashboard¶

The Sistemo web dashboard provides a graphical interface for managing your machines, images, volumes, and networks. It runs alongside the daemon and is accessible from your browser.

Accessing the dashboard¶

The dashboard is available at:

http://localhost:7777/dashboard/

The daemon must be running before you can access it. Start it with:

sudo sistemo up

Or, if you've installed the systemd service:

sistemo service install
sudo systemctl start sistemo

First-time setup¶

On your first visit, the dashboard displays an admin account creation form. Fill in:

• Username -- 3 to 64 characters
• Password -- 8 characters minimum

After submitting, you are logged in automatically and taken to the overview page.

Authentication¶

The dashboard uses JWT-based sessions stored in the browser. How authentication works depends on where you access the dashboard from.

Localhost bypass (CLI only)¶

When the CLI runs on the same host as the daemon, API authentication is bypassed automatically. Requests from 127.0.0.1 or ::1 skip all auth checks. This means sistemo machine list, sistemo machine deploy, and other CLI commands work without any credentials on localhost.

The browser dashboard still requires login — the bypass only applies to direct API calls from localhost.

Remote access¶

If you access the dashboard from another machine on the network, you must log in with the admin credentials you created during first-time setup.

API key¶

For scripts or remote API access, set HOST_API_KEY as an environment variable. This is an env-var only setting — it cannot be placed in config.yml. If you use the systemd service, set it in the service environment:

# Option 1: environment variable
export HOST_API_KEY="your-secret-key"
sudo -E sistemo up

# Option 2: set it in the systemd unit override
sudo systemctl edit sistemo
# Add: Environment=HOST_API_KEY=your-secret-key

Then pass the key in API requests:

curl -H "X-API-Key: your-secret-key" http://your-host:7777/api/v1/machines

Resetting your password¶

If you forget your admin password, reset it from the CLI:

sistemo admin reset-password

This prompts for a new password and updates the stored credentials.

Dashboard pages¶

Overview¶

The landing page shows a summary of your host:

• Resource counts -- machines, images, volumes, networks
• Host info -- hostname, CPU cores, total RAM, disk usage
• Real-time polling -- data refreshes every 10 seconds

Machines¶

The machines page lists all machines with status filters:

• All -- every machine regardless of state
• Running -- currently active machines
• Stopped -- machines that have been shut down
• Error -- machines that failed to start or encountered a runtime error

Deploying a new machine¶

Click Deploy to create a machine from one of four sources:

1. Registry image -- pull from the Sistemo image registry
2. Docker image -- convert a Docker/OCI image into a machine root filesystem
3. URL -- download a rootfs from a direct URL
4. Existing volume -- boot from a volume you've already created

Machine actions¶

Each machine in the list supports:

Machine detail page¶

Click a machine name to open its detail page with tabs:

• Terminal -- in-browser SSH (see below)
• Logs -- boot and runtime log output
• Ports -- exposed port mappings
• Volumes -- attached volumes and mount points
• Config -- CPU, memory, network, and other settings

Terminal¶

The dashboard includes a full in-browser terminal powered by xterm.js over WebSocket.

• Opens automatically when you navigate to a running machine's terminal tab
• Provides the same experience as sistemo machine ssh <name>
• Supports copy/paste, scrollback, and resize

Images¶

The images page shows all local images with their size and source.

Available actions:

• Download from registry -- browse and pull images from the Sistemo registry
• Build from Docker image -- convert a Docker image with real-time build progress
• Delete -- remove unused images to free disk space

Volumes¶

Manage persistent storage volumes:

• Create -- provision a new volume with a specified size
• Resize -- grow an existing volume
• Delete -- remove a volume (must be detached first)
• Attach -- connect a volume to a machine
• Detach -- disconnect a volume from a machine

The volume list displays:

Networks¶

Manage isolated machine networks:

• Create -- set up a new network with an optional custom subnet
• Delete -- remove a network (must have no machines attached)

The list shows each network's name, subnet, and the number of machines currently connected.

History¶

A full audit log of every operation performed through the dashboard or CLI:

• Filter by action type (create, delete, start, stop, etc.)
• Paginated with 50 entries per page
• Each entry shows timestamp, action, target resource, and result

System¶

The system page provides host-level information:

• CPU -- model, core count
• RAM -- total and available memory
• Kernel -- Linux kernel version
• Disk usage -- visual progress bar showing used vs. available space
• Machine resource allocation -- total vCPUs and memory allocated across all machines

Remote access¶

To expose the dashboard securely over a network:

1. Set an API key:

   export HOST_API_KEY="a-strong-random-secret"
   

2. Start the daemon with the key available:

   sudo -E sistemo up
   

3. Put a reverse proxy (nginx, Caddy, etc.) in front of port 7777 with TLS termination:

   server {
       listen 443 ssl;
       server_name sistemo.example.com;
   
       ssl_certificate     /etc/ssl/certs/sistemo.pem;
       ssl_certificate_key /etc/ssl/private/sistemo.key;
   
       location / {
           proxy_pass http://127.0.0.1:7777;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }