🚀 Getting Started

Welcome to the portal — your secure control plane for fleets of Linux, Android, and NanoKVM devices deployed anywhere on the internet. Everything is done through a lightweight agent that calls home over an encrypted WebSocket, so your devices never need a public IP or open ports.

The 3-minute onboarding

1. Go to Devices → + Add Device.
2. Pick a tab: 🐧 Linux, 🤖 Android, 🖥️ NanoKVM, or 🪟 Windows.
3. Fill in the name, optional note, and group.
4. Copy the install command, paste it into your device's shell, press Enter.
5. The device appears online in under 30 seconds — start using it.

What you can do with a connected device

➕ Adding Devices

All device types share the same Add Device dialog. Fill in the shared fields at the top (Name, Note, Group), then pick the device type tab — the install command updates live as you type so you can copy the exact one-liner for your device.

🐧 Linux / Raspberry Pi

Works on Debian, Ubuntu, Raspberry Pi OS, Alpine, and most modern Linux distros. The installer registers the device, installs xaccel-agent as a systemd service, and starts it immediately.

curl -s 'https://HOST/api/install/install.sh?key=...&name=MyPi' | sudo bash

• The setup key is taken from Settings → Setup Key.
• Uninstall with sudo systemctl disable --now xaccel-agent && sudo rm -rf /opt/xaccel-agent /etc/xaccel.
• Agent logs: journalctl -u xaccel-agent -f.

🤖 Android (Termux)

No root, no Play Store. Install Termux from F-Droid, open it, paste the command from the Android tab.

• The installer also installs DroidVNC-NG so you get full screen access from the browser — open it, tap Start, grant the screen-capture permission once.
• A VNC tunnel is auto-created on port 5900 so the portal displays the screen inline.
• To survive reboots, install Termux:Boot (also on F-Droid) — the installer drops the right startup script automatically.

🖥️ NanoKVM

Sipeed NanoKVM devices run BusyBox on a SiPeed SoC. The installer is BusyBox-safe and targets /etc/kvm/. SSH into the NanoKVM (enable SSH in its web UI under Settings → SSH; default creds are root / root), then:

curl "https://HOST/install/nanokvm?key=...&name=Rack1-KVM" | sh

• The installer also pins the NanoKVM web UI to H.264 direct mode — sharper picture, lower latency, especially over tunnels.
• It installs a tiny boot-time init script (/etc/init.d/S98xaccel-kvm-patch) so the H.264 setting is re-applied after every firmware update (which normally resets the web UI files).
• Uninstall: /etc/init.d/S99xaccel stop; rm -rf /etc/kvm /etc/init.d/S99xaccel /etc/init.d/S98xaccel-kvm-patch.

Manual registration (fallback)

Any device type can also be pre-registered by clicking Register this device manually → in the Add Device dialog. You'll get a row in the table with status offline; the agent then picks up that identity when it first connects using the matching name.

🎛️ Remote Access

Once a device is online you have three complementary access methods.

💻 Web Console

Full interactive shell in your browser using xterm.js. Pick a device from Web Console, click Connect. Under the hood we open a dedicated shell channel over the existing WSS and stream PTY data byte-for-byte — so colors, TUI apps (htop, vim), and keybindings all work.

• Resize the browser window — the pty is resized automatically.
• Copy text with your OS's regular copy shortcut; paste with Ctrl+Shift+V (Linux/Win) or Cmd+V (macOS).
• Sessions are tied to your browser tab; closing the tab terminates the shell cleanly.

🔗 xTunnels

A tunnel exposes a port on the device to the outside world. Pick the device, pick the type, and the portal gives you a public URL or port:

• HTTP/HTTPS — public subdomain like web-.HOST, served over TLS with our wildcard cert. Perfect for web UIs (OctoPrint, HomeAssistant, IP cameras).
• SSH — a public TCP port on our edge you can ssh into directly.
• Custom TCP — for VNC, RDP, MySQL, arbitrary protocols. We give you a host:port.

Tunnels are time-limited by default (configurable per tunnel). When you close a tunnel, the underlying TCP listener and any per-port firewall rule are torn down automatically.

🖥️ NanoKVM (KVM Devices)

For NanoKVM units, the KVM Devices page embeds the NanoKVM's own H.264 video streamer inside an iframe, proxied through us. You get:

• Live HDMI video of the target machine's monitor output.
• Full USB keyboard + mouse emulation (BIOS / UEFI accessible).
• Power control (ATX power + reset) via the NanoKVM's ribbon cable.
• Virtual media (mount an ISO from portal uploads).

📈 Monitoring & Alerts

Every connected agent reports a heartbeat every 30 seconds with CPU, memory, disk, temperature, and uptime. Historic data is retained for 30 days of 1-minute resolution by default.

Monitoring page

Pick a device and a time range to see trend charts for:

• CPU usage (percent)
• Memory used / total
• Disk used / total on /
• Temperature (where supported by the hardware)
• Network throughput (up / down)

Custom Metrics

Agents can publish any metric you want with a one-liner from a script. Useful for application-level data (queue depth, latency, user count). See Custom Metrics for the full API and examples.

Alerts

On the Alerts page, create rules such as "CPU > 90% for 5 minutes" or "Device offline for 2 minutes". When a rule fires, we'll:

• 📧 Email the rule owner
• 🔔 Push browser notifications (if enabled in Settings)
• 🔗 Call any configured webhook with a structured JSON payload
• 📲 Optionally SMS if you've wired Twilio under your account

Recent alert events are shown on the Dashboard and on the Alerts page so you can acknowledge / silence individual events.

📁 Files & OTA Updates

Two related tools, used together.

File Upload

Push any file (config, cert, script, binary) from the portal to one or many devices:

• Destination path is set per upload — agent creates parent directories as needed.
• Optional schedule (cron-style): deploy at a quiet time window.
• Optional post-deploy command: for example, restart a service after dropping a new config.
• Transfer is integrity-checked with a SHA-256 hash so partial transfers never get applied.

OTA Updates

A higher-level workflow for firmware/software packages. Use it to:

• Upload a versioned artifact (.tar.gz, .deb, .apk, raw binary).
• Roll it out to a subset first (canary), then the rest of the fleet.
• Automatic rollback if the health-check command fails after deploy.
• Full audit log of who pushed what, when, and to which devices.

👥 Groups, SSH Keys & API Keys

Groups

A group is a named collection of devices. Use groups to:

• Filter the Devices page instantly.
• Target batch jobs / file pushes / OTAs at a subset of the fleet.
• Grant specific users access to only the devices in their group (see Users).

SSH Keys

Upload your public SSH keys here to have them auto-provisioned to ~/.ssh/authorized_keys on Linux devices you add later. Supports ed25519, rsa, and ecdsa keys.

API Keys

For automation. Issue a key with a label (e.g. "ci-bot") and scope (read-only / read-write). Use the key as a Authorization: Bearer ... header on any API endpoint:

curl -H "Authorization: Bearer xio_XXXXXXXX" \
           https://HOST/api/devices

Keys are shown exactly once at creation time — you cannot retrieve the secret again, so copy it into your vault immediately.

💳 Billing & Subscription

Your subscription is priced based on the number of active devices in your account. "Active" = seen online within the last 30 days.

• Plan tiers unlock higher device counts, longer metric retention, and premium features (SCIM, SSO, white-label).
• Billing is prorated — upgrade or downgrade at any time from Billing → Change Plan.
• Invoices are downloadable as PDF from the same page.
• Payment methods are tokenized by Authorize.net — we never see your full card number or CVV.

🔒 Account Security

Things you can do right now to harden your login.

Two-factor authentication (2FA)

1. Go to Settings → Two-Factor Authentication.
2. Click Enable 2FA and scan the QR with Google Authenticator, Authy, or 1Password.
3. Enter the 6-digit code to confirm — save the 8 backup codes somewhere safe.

After enabling, every login on a new browser will ask for the code in addition to your password.

Strong password

We enforce minimum 8 characters + mixed case + a digit. Under the hood passwords are hashed with bcrypt (12 rounds), never stored or logged in plaintext.

Email verification

A yellow banner appears at the top until you click the verification link we send on signup. Verification is required for password reset and billing changes.

Active sessions

Each browser/device you log in from gets a separate session. Sign out of all sessions from Settings → Active Sessions if a device is lost.

🛡️ Security — What We Do For You

A short plain-English summary of the defenses built into the portal. For the technical details, your administrator can open the Admin Docs.

Encryption in motion

• All web traffic → TLS 1.2+ with a wildcard certificate; HTTP is redirected to HTTPS.
• Agent ↔ portal → WSS (WebSocket over TLS). The same cert chain; no fallback to plaintext.
• Tunnels → TLS all the way to our edge, then reuse the authenticated WSS channel to your device. No raw TCP on the public internet except our own edge port.

Encryption at rest

• Passwords → bcrypt(12) — slow on purpose, to defeat offline cracking.
• Setup keys, API keys, SCIM bearer tokens → HMAC-SHA-256 fingerprints stored server-side; the secret is only ever shown to you once.
• Database backups → encrypted with a separate KMS key and rotated nightly.

Device isolation

• Each device only sees its own traffic — WebSocket multiplexing uses per-device tokens.
• Tunnels are scoped to a single device + port pair; a compromised tunnel cannot be pivoted to other devices.
• Per-tenant data isolation enforced at the query level (every read/write filters by tenant_id).

Operational security

• Rate-limited auth endpoints — brute force attempts are throttled and eventually temp-banned by IP.
• All admin actions produce an Audit Log entry (accessible to admins).
• We run continuous vulnerability scans on our infrastructure and patch within 48 hours of any critical CVE.
• Webhooks outgoing from the portal are signed with HMAC-SHA-256 — your receiver can verify we sent them.

❓ FAQ & Troubleshooting

My device shows as "offline" but I just installed the agent.

Check the agent log: sudo journalctl -u xaccel-agent -n 100 --no-pager. Common causes:

• Firewall blocking outbound tcp/443 — the agent needs to reach the portal over HTTPS/WSS.
• Captive portal / corporate proxy — set HTTPS_PROXY=https://user:pass@proxy:port in /etc/systemd/system/xaccel-agent.service.d/override.conf.
• Time drift — very old system clocks fail TLS validation. Run sudo timedatectl set-ntp true.

I can't SSH through an SSH tunnel.

Verify the tunnel shows status active. Then: ssh -p @. If the connection hangs, the device agent may have lost its WS link — check agent logs. If you get "permission denied", the SSH tunnel reached the device but that device's sshd refused the credentials — this is normal; fix your SSH key setup on the device.

NanoKVM video is blurry / slow over the tunnel.

Confirm H.264 direct mode is set: on the NanoKVM web UI go to Settings, make sure Video Mode is direct. The xaccel installer enforces this automatically and re-applies it after firmware updates.

I lost my 2FA device.

Use one of the 8 backup codes you saved when enabling 2FA. If you also lost those, contact your account owner or support to perform an identity-verified reset.

How do I delete all my data?

From Settings → Danger Zone → Delete Account. We'll email you a confirmation link; clicking it performs an irreversible delete within 24 hours (GDPR-compliant). Exports can be requested first from the same page.

Where are the API docs?

All endpoints are documented at https://HOST/api/docs — OpenAPI 3.0 with a live "try it" playground. Use an API key (see Section 6) to authenticate.