v1.0.0 · 5-minute setup

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.

FlagDefaultWhat it does
--dir/opt/starkristaInstall location (binary, .env, database)
--port8082Web UI port, for a fresh install
--channelstableRelease 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.

Good to know. StarkRista never modifies your switch's auth or management config. It logs in with the credentials you give it, the same way an engineer would.

03First login

1

Open http://<host>:8082

The installer prints the exact URL when it finishes.

2

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.

3

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.

VariableDefaultPurpose
APP_PORT8082Web UI port
APP_USER / APP_PASSadmin / randomFirst admin — used once, on the first start
VIEWER_USER / VIEWER_PASS—Optional read-only user, also first start only
JWT_SECRETrandomSigns logins and encrypts stored switch passwords. Never change it.
ARISTA_HOST / _USER / _PASS—Optional: add a first switch on first start
ARISTA_INSECUREtrueTrust self-signed certs for that first switch
PUBLIC_BASE—URL switches use to fetch firmware from StarkRista
UPDATE_CHECKtruefalse never contacts the update server
UPDATE_CHANNELstableDefault 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.
Safety rail. The last admin can't be deleted or demoted. Locked out anyway? Stop the service, run 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

SwitchArista EOS with eAPI enabled, a privilege-15 account
StarkRista hostLinux, x86-64 or ARM64 — any distro (static binary)
NetworkHTTPS (443) from the host to each switch's management address
Disk~13 MB binary, plus the database (port history is kept 14 days)
BrowserAny current Chrome, Edge, Firefox or Safari

12Troubleshooting

  • "connection refused" — eAPI is probably off. Check show management api http-commands on 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 50 shows 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.
Still stuck? Email [email protected] with the log lines. We read every one.

13Uninstall

$ sudo systemctl disable --now starkrista
$ sudo rm /etc/systemd/system/starkrista.service
$ sudo rm -rf /opt/starkrista   # deletes the database and backups too