Getting started
One command installs StarkRista on a Linux host. Enable eAPI on your switch, add it in the UI, and start clicking. Below is the long version.
01Install
StarkRista ships as a single static Linux binary (x86-64 or ARM64) — it runs on any modern distro with nothing else to install. On the host that will run it:
Linux · one-liner$ curl -fsSL https://starkrista.com/install.sh | sudo bash # → binary → /opt/starkrista/starkrista-bin # → config → /opt/starkrista/.env (random admin password + secret) # → service → systemd unit "starkrista", enabled and started
The installer downloads the build for your CPU, checks its SHA-256 checksum, and prints the URL and the admin password when it's done. Running it again later upgrades the binary in place and keeps your .env and database.
| Flag | Default | What it does |
|---|---|---|
| --dir | /opt/starkrista | Install location (binary, .env, database) |
| --port | 8082 | Web UI port, for a fresh install |
| --channel | stable | Release channel (stable or beta) |
| --no-systemd | — | Don't create or restart the systemd unit |
| --no-start | — | Install, but don't start the service yet |
Passing flags$ curl -fsSL https://starkrista.com/install.sh | sudo bash -s -- --port 9000
02Prepare your switch
StarkRista talks to your Arista switch over the standard eAPI. If you've never used it, enable it once:
EOS CLI · on your switchleaf-01# configure terminal leaf-01(config)# management api http-commands leaf-01(config-mgmt-api)# protocol https leaf-01(config-mgmt-api)# no shutdown leaf-01(config-mgmt-api)# end leaf-01# show management api http-commands
StarkRista needs a switch account with privilege 15 to read and change config.
03First login
Open http://<host>:8082
The installer prints the exact URL when it finishes.
Log in as admin
Use the password the installer printed (it's also APP_PASS in /opt/starkrista/.env). That account is created on the first start; after that, users live in the database and you manage them from the Users page.
Change the password
Users → Change password. Then add your first switch.
04Add your switches
Open Switches (admins only) and add each switch: a name, its management IP or hostname, the eAPI username and password, and optionally an SSH user for firmware transfers and the management VRF. Test checks the connection before you save.
- Manage as many switches as you like from one install — pick the active one from the selector in the sidebar.
- Switch passwords are encrypted at rest (AES-256-GCM, key derived from
JWT_SECRET). - Self-signed switch certificate? Tick Insecure TLS for that switch.
05The .env file
Deployment settings live in /opt/starkrista/.env. After editing it, restart with sudo systemctl restart starkrista.
| Variable | Default | Purpose |
|---|---|---|
| APP_PORT | 8082 | Web UI port |
| APP_USER / APP_PASS | admin / random | First admin — used once, on the first start |
| VIEWER_USER / VIEWER_PASS | — | Optional read-only user, also first start only |
| JWT_SECRET | random | Signs logins and encrypts stored switch passwords. Never change it. |
| ARISTA_HOST / _USER / _PASS | — | Optional: add a first switch on first start |
| ARISTA_INSECURE | true | Trust self-signed certs for that first switch |
| PUBLIC_BASE | — | URL switches use to fetch firmware from StarkRista |
| UPDATE_CHECK | true | false never contacts the update server |
| UPDATE_CHANNEL | stable | Default release channel |
06HTTPS & reverse proxy
StarkRista serves plain HTTP. On a laptop or a locked-down jump host that's fine; anywhere else, put it behind a reverse proxy that terminates TLS. With Caddy it's two lines (certificates are automatic):
/etc/caddy/Caddyfilestarkrista.example.com {
reverse_proxy 127.0.0.1:8082
}
With nginx, pass WebSocket upgrades through — the live port and BGP views use them:
nginxlocation / {
proxy_pass http://127.0.0.1:8082;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
07Users & roles
Users and roles live on the Users page.
- admin — full read/write: change config, push firmware, manage switches and users, install updates.
- viewer — read-only. Enforced in the API middleware, so it holds for scripts too, not just the UI.
sqlite3 /opt/starkrista/starkrista.db "DELETE FROM users", and start it again — the admin from .env is re-created.
08Config backups
Open Backups and take a snapshot of the running-config before a risky change — give it a label so you'll find it later. Pick any two snapshots to see a unified diff, or download one as a text file. Snapshots are stored in StarkRista's database, per switch.
09Updates
StarkRista keeps itself up to date. Every few hours it checks starkrista.com for a newer version; admins see it on the Updates page with the release notes, and install it with one click. Pick a mode there:
- Notify me (default) — show new versions, install when you click.
- Install automatically — install during a nightly window you choose.
- Off — never check on its own.
Every release is signed. StarkRista verifies the signature and checksum, backs up the database, swaps the binary and restarts — the UI is back within seconds. If a new version fails to start, the previous one is restored automatically; Roll back on the Updates page does the same by hand.
From a shell$ curl -fsSL https://starkrista.com/install.sh | sudo bash # upgrade to the latest $ sudo /opt/starkrista/starkrista-bin --rollback # back to the previous version $ sudo systemctl restart starkrista
Air-gapped network? Set UPDATE_CHECK=false and update with the installer when it suits you.
10HTTP API
Everything in the UI is a call to the StarkRista HTTP API. Log in for a token (valid 24 hours), then send it as a bearer token. With several switches, pick one with the X-Switch-Id header.
Example$ TOKEN=$(curl -s http://localhost:8082/api/auth/login \ -d '{"username":"admin","password":"…"}' -H 'Content-Type: application/json' | jq -r .token) $ curl -H "Authorization: Bearer $TOKEN" http://localhost:8082/api/ports # → JSON: every interface with its state and counters
11Requirements
| Switch | Arista EOS with eAPI enabled, a privilege-15 account |
| StarkRista host | Linux, x86-64 or ARM64 — any distro (static binary) |
| Network | HTTPS (443) from the host to each switch's management address |
| Disk | ~13 MB binary, plus the database (port history is kept 14 days) |
| Browser | Any current Chrome, Edge, Firefox or Safari |
12Troubleshooting
- "connection refused" — eAPI is probably off. Check
show management api http-commandson the switch. - TLS / certificate errors — the switch uses a self-signed certificate. Tick Insecure TLS on that switch.
- 401 from the switch — wrong eAPI username or password, or the account lacks
privilege 15. - Service won't start —
sudo journalctl -u starkrista -n 50shows why on the first lines. - An update failed — the Updates page shows the error; nothing was changed. If a new version misbehaves, use Roll back.
13Uninstall
$ sudo systemctl disable --now starkrista $ sudo rm /etc/systemd/system/starkrista.service $ sudo rm -rf /opt/starkrista # deletes the database and backups too