v1.4.0 · 5-minute setup

Getting started

Download the binary, point it at a switch that has eAPI enabled, log in. That's it. Below is the long version.

01Install

StarkRista ships as a single self-contained Linux binary. The installer drops it at /opt/starkrista, writes a starter .env, and sets up a systemd unit.

Linux · one-liner install$ git clone https://console-nati.starkhive.ai/git/StarkRista-Pub.git
$ cd StarkRista-Pub
$ sudo ./install.sh
# → binary    → /opt/starkrista/starkrista-bin
# → config    → /opt/starkrista/.env  (FROM EXAMPLE — edit before starting)
# → systemd   → /etc/systemd/system/starkrista.service
Installer flags$ sudo ./install.sh --dir /srv/starkrista --port 9000 --no-systemd

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
Enabled · HTTPS port 443 · running
Good to know. StarkRista never modifies your switch's auth or management config. It logs in with credentials you provide, the same way an engineer would.

03Configure & run

Tell StarkRista which switch to manage by editing /opt/starkrista/.env:

/opt/starkrista/.envARISTA_HOST=10.0.0.1
ARISTA_USER=admin
ARISTA_PASS=<your eAPI password>
ARISTA_INSECURE=true          # self-signed switch certs
APP_USER=admin             # first UI admin (bootstrap)
APP_PASS=<set a strong one>
APP_PORT=8082
JWT_SECRET=<random hex, e.g. openssl rand -hex 32>

Then start it:

$ sudo systemctl enable --now starkrista
$ sudo journalctl -u starkrista -f
▸ connected to leaf-01 (EOS 4.32.1F)
▸ listening on :8082

04First login

1

Open http://localhost:8082

On first launch you'll be prompted to create the first admin account. This account is the only one that can later create or demote other admins.

2

Set an admin password

StarkRista hashes it with bcrypt and stores it in a local SQLite file (~/.starkrista/state.db). Forget the password? Delete the file and start over.

3

You're in

You should now be looking at the live dashboard. Try right-clicking a port.

05CLI flags

FlagDefaultWhat it does
--switch—Switch hostname or IP (required)
--useradmineAPI user
--port8082UI port
--bind127.0.0.1Bind address
--tls-cert—TLS cert for the UI
--state-dir~/.starkristaLocal DB & backups
--insecure-skip-verifyfalseTrust self-signed switch certs

06Config file

Anything you can pass as a flag, you can put in a YAML file:

~/.starkrista/config.ymlswitch: "10.0.0.1"
user: "admin"
bind: "0.0.0.0"
port: 8082
tls:
  cert: "/etc/ssl/starkrista.pem"
  key: "/etc/ssl/starkrista.key"
backups:
  enabled: true
  interval: "24h"
  keep: 30

07TLS & certificates

By default StarkRista listens on 127.0.0.1:8082 over plain HTTP — fine for laptop use. For a jump host or shared install, terminate TLS with a real cert:

$ ./starkrista \\
    --switch 10.0.0.1 \\
    --bind 0.0.0.0 \\
    --tls-cert /etc/ssl/starkrista.pem \\
    --tls-key  /etc/ssl/starkrista.key

08Adding a switch

Today StarkRista manages one switch per process. If you have three switches, run three processes — each on its own port. The unified multi-switch view is on the roadmap for Q3 2026.

09Managing users

Users & roles live in the Settings → Users panel.

  • admin — full read/write. Can change config, push firmware, manage other users.
  • viewer — read-only. Cannot modify anything, even via the HTTP API. Enforced at middleware.
Safety rail. StarkRista refuses to delete or demote the last admin. If you lock yourself out, edit ~/.starkrista/state.db directly (it's plain SQLite).

10Config backups

Enable scheduled snapshots in the config file (see above) or trigger one anytime from Settings → Backups. Each snapshot is stored as a flat text file under ~/.starkrista/backups/ — you can rsync them off to your usual git-of-config repo.

11Upgrading

$ ./starkrista upgrade
▸ current: 1.4.0
▸ latest:  1.4.1
▸ ok to replace ./starkrista? [y/N] y
▸ backed up old binary to ./starkrista.bak
▸ done. run ./starkrista to restart.

12HTTP API

Every action in the UI is a call to the StarkRista HTTP API. Auth is a short-lived JWT in a cookie or Authorization header.

Get all interface state$ curl -H "Authorization: Bearer $TOKEN" \\
    http://localhost:8082/api/v1/interfaces
# → JSON: array of every interface with state, counters, lldp

Full API reference is in ./starkrista openapi (a generated OpenAPI 3.1 doc).

13Requirements

Switch OSEOS 4.20 or newer with eAPI enabled
StarkRista hostany 64-bit · linux, macos, windows
Memory~30 MB resident · ~80 MB with a 100k-route BGP table loaded
Disk~50 MB for binary + snapshots
Browserany modern browser · Safari 15+, Firefox 100+, Chromium 100+

14Troubleshooting

  • "connection refused" — check the switch's show management api http-commands output; eAPI is probably off.
  • "tls: bad certificate" — your switch is using a self-signed cert. Pass --insecure-skip-verify or import the cert.
  • "401 from switch" — wrong eAPI user/password. StarkRista doesn't reuse OS-level creds; check username … privilege 15.
  • BGP page hangs — should never happen on 1.4+. If it does, attach ./starkrista doctor --diag output to a GitHub issue.
Still stuck? Open an issue on GitHub or email [email protected]. We read every one.