🚀 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

Install the Xaccel Agent APK directly — no Termux, no third-party apps, no prerequisite software. Generate an enrollment code or QR from the Android tab in Add Device, then either scan it or open the link on the device to install and auto-enroll in one step.

• Works standalone on any Android 8.0+ device. Telemetry (battery, storage, network, CPU, uptime, etc.) requires no special permissions.
• Rooted devices automatically unlock additional capabilities once the app detects su: remote reboot / shutdown / hard reboot, an interactive root shell from the device's Console tab, silent self-update, and (agent 1.4.0+) built-in remote screen viewing and control — see 🎛️ Remote Access → 🤖 Android Screen Sharing below. No extra setup is needed — the agent detects root at runtime.
• Non-rooted devices still report full telemetry and support screen viewing (1.4.0+); privileged actions (reboot, shell, remote input) stay unavailable and are hidden in the UI.
• Uninstall like any normal app: long-press the icon → Uninstall, or Settings → Apps → Xaccel Agent → Uninstall.

🖥️ 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.

🪟 Windows Devices & RDP

Windows machines join your fleet the same way Linux devices do — a lightweight agent registers the machine and keeps an outbound WSS connection open, so no inbound firewall rules or port-forwarding are needed. Once online, a Windows device appears on the Windows Devices page alongside its live metrics.

Installing the Windows agent

1. Go to Devices → + Add Device → 🪟 Windows, fill in the name and group.
2. Open an elevated PowerShell (Run as Administrator) on the target machine.
3. Paste the one-line installer shown in the dialog:

iwr -useb 'https://HOST/install/windows.ps1?key=...&name=MyPC' | iex

• The installer registers the device, installs the agent as a Windows Service (auto-start on boot), and starts it immediately.
• You can also download the signed MSI/EXE directly from https://HOST/download/windows/latest for imaging or Group Policy deployment.
• The setup key comes from Settings → Setup Key. For fully hands-off imaging, use Zero-Touch Provisioning (next section) instead of a setup key.

Remote Desktop (RDP) over a tunnel

The recommended way to reach a Windows desktop is an RDP tunnel — RDP is never exposed to the public internet; it stays behind the device's authenticated WSS channel.

1. Open the device on the Tunnels (xTunnels) page.
2. Create a tunnel of type RDP (targets port 3389 on the device).
3. Click Download .rdp file — the portal generates a ready-to-use .rdp profile pointing at our edge host and the tunnel's assigned port.
4. Open the .rdp file with the Windows Remote Desktop client (or Microsoft Remote Desktop on macOS) and sign in with the machine's own Windows credentials.

🎫 Zero-Touch Provisioning

Zero-Touch Provisioning lets devices register themselves automatically on first boot — no setup key to paste, no manual step per unit. You bake a provisioning token into a base image once; every device flashed from that image self-registers keyed by its hardware MAC address. Ideal for factory imaging and large rollouts.

1 · Create a provisioning token

Go to Settings → Zero-Touch Provisioning and click Create Token. Configure:

• Label — a human-readable name (e.g. "Factory batch Q3").
• Default group — new devices are auto-assigned to this group.
• Default tags — tags applied to every device provisioned with this token.
• Max uses — how many devices may register with it (0 = unlimited).
• Expiry — an optional date/time after which the token stops working.
• IP allowlist — optional list of source IPs allowed to provision (e.g. your factory's egress IP). Leave empty to allow any source.
• Allow re-provisioning — if enabled, a device with a MAC already seen will have its credentials rotated and refreshed instead of being rejected; if disabled, re-registration is idempotent and returns the existing credentials.

2 · Bake it into your base image

Place the portal URL and token in /etc/xaccel/provision.conf in the image you flash to devices:

# /etc/xaccel/provision.conf
SERVER_URL=https://HOST
PROVISION_TOKEN=prov_xxxxxxxxxxxxxxxxxxxx

Flash this image to as many devices as you like. Nothing else per-device is required.

3 · Devices auto-register on first boot

On first boot the agent reads provision.conf and POSTs its MAC address and token to SERVER_URL/api/provision. The server:

• Validates the token (active, not expired, under its max-uses limit, source IP in the allowlist if set).
• Normalizes the MAC and creates a new device row — assigned to the token's default group and tags — then returns a unique device_id and secret.
• The agent persists those credentials and uses them for all subsequent authenticated WSS connections.
• A device already registered under the same MAC returns its existing credentials (or has them rotated, if re-provisioning is allowed).

Every provisioning event is written to the audit log, and you can see exactly which devices a token created from Settings → Zero-Touch Provisioning → (token) → Devices.

🎛️ 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).

🤖 Android Screen Sharing

Since agent version 1.4.0, Android devices have a VNC server built directly into the Xaccel Agent app — no Termux, no separate VNC app to install or start on the device. It reuses the same xTunnels mechanism above:

• Create a tunnel on the Android device with Remote Port 5900, then click the 🖥️ VNC button next to it — the same in-browser noVNC viewer used for Linux VNC tunnels opens automatically.
• One-time consent dialog: Android always shows a system prompt ("Start recording or casting?") the first time screen capture starts on a device — this is an OS-level protection that can't be bypassed by any app. On rooted devices, the agent automates this by reading the dialog with uiautomator and tapping "Start now" for you; on non-rooted devices, someone taps it once on the device.
• Remote control (rooted only): clicks and drags in the viewer become input tap/input swipe commands, and typing is injected via input keyevent/input text — giving full interactive control, not just a read-only view. This uses root shell input injection rather than an Accessibility Service, since Accessibility Services can't inject arbitrary key codes or text. Modifier-key combos (e.g. Ctrl+C) aren't supported.
• Non-rooted devices support screen viewing only — the viewer opens the same way, but taps/keystrokes in the browser aren't sent back to the device.
• Screen capture only starts when a VNC connection actually arrives, and stops when the tunnel closes — the device isn't recording its screen in the background.

📈 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.

📊 Custom Metrics

Beyond the built-in system metrics (CPU, memory, disk, temperature, network), the Custom Metrics page lets you define and track application-level metrics — anything your scripts can measure, like queue depth, request latency, active users, or sensor readings.

Define a metric

1. Open Custom Metrics → + New Metric.
2. Give it a name, unit, and (optionally) a description.
3. Save — the metric is now ready to receive values.

Publish values from a device

Agents publish metric values over the same encrypted WSS channel, or you can push from any script using an API key:

curl -X POST https://HOST/api/metrics/<metric_id>/ingest \
     -H "Authorization: Bearer xio_XXXXXXXX" \
     -H "Content-Type: application/json" \
     -d '{"value": 42, "device_id": "dev-abc123"}'

View & use the data

• See the latest value, a summary (min/max/avg), and the full history of values for each metric.
• Custom metrics can be used as the trigger field for Alerts — e.g. "queue_depth > 1000 for 10 minutes".
• Old values can be cleared per metric when you no longer need the history.

📋 Log Aggregation

The Log Aggregation page collects logs from your connected devices into one searchable place, so you don't have to SSH into each box to read journalctl. The header shows live counts of Errors, Warnings, and Info messages across the current filter.

The Log Viewer

• Devices sidebar — pick All Devices or a single device; the count next to each shows how many log lines match the current filter.
• Level — filter by severity (Error / Warning / Info / Debug), or All Levels.
• Source — filter by the log source/tag (e.g. a service name), or All Sources.
• Since / Until — restrict to a date-time window.
• Search messages… — free-text search across the message body.

Matching lines appear in the table with their Timestamp, Level, Source, and Message. Results stream in live as new logs arrive from the agents.

Export & retention

• Use Export to download the currently-filtered logs for offline analysis or archival.
• You can clear stored logs when they are no longer needed.

⚙️ Batch Jobs & Fleet

Run commands across many devices at once, on demand or on a schedule, and manage your whole fleet from a single place.

Batch Jobs

On the Batch Jobs page, create a job by giving it a name, the command (or script) to run, and the target devices:

• Target one device, several, or an entire group.
• Run now, or set an execute time to run later.
• Each device returns its own result (exit code + output) so you can see per-device success/failure.

Scheduled & recurring jobs

For jobs that should run on a repeating schedule, use the scheduler:

• Create a schedule with a recurring cadence (e.g. nightly maintenance).
• Toggle a schedule on/off without deleting it.
• Run now to trigger a scheduled job immediately, outside its normal cadence.

Fleet management

The Fleet page operates across your entire estate at once:

• Dispatch fleet-wide jobs and watch aggregate status roll up across all devices.
• Slice the fleet by groups and tags.
• Check the deployed agent version across the fleet and trigger an agent update where needed.

📁 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.

🔗 Webhooks

Webhooks push portal events to your own systems in real time — send an alert firing, a device going offline, or a job completing straight into Slack, PagerDuty, or your internal automation.

Create a webhook

1. Open Webhooks → + Add Webhook.
2. Enter the destination URL that should receive the HTTP POST.
3. Choose which events it subscribes to.
4. Save — a signing secret is generated for the endpoint.

Verifying & managing deliveries

• Test — send a sample payload to confirm your receiver is reachable and parses it correctly.
• Deliveries — inspect the recent delivery history (status codes, retries) for each webhook to debug failures.
• Rotate secret — issue a new signing secret if the old one may have been exposed.
• Edit / Delete — change the URL and subscriptions, or remove the webhook.

📑 Reports

Reports turn your fleet data into recurring, delivered summaries — so stakeholders get an inventory, uptime, or activity report on a schedule without logging in.

Schedule a report

1. Open Reports → + New Schedule.
2. Choose the report type/content and the cadence (e.g. weekly).
3. Set the recipients/delivery for the generated report.
4. Save the schedule.

Manage schedules

• Run now — generate a report immediately, without waiting for the next scheduled run.
• Edit / Delete — adjust the content, cadence, or recipients, or remove a schedule.

👥 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.

⚙️ Settings & Account

The Settings page is the hub for account-wide configuration. The main sub-features:

🔑 Setup Key

The setup key authorizes new device installs. It is embedded in the install commands shown in the Add Device dialog. If you suspect it has leaked, click Regenerate — existing devices keep working, but the old key can no longer enroll new devices. For fully hands-off enrollment, use Zero-Touch Provisioning tokens instead.

🌐 IP Whitelist

Restrict access to your account to specific source IPs or CIDR ranges. Add the office/VPN egress addresses you trust; once the list is non-empty, logins from other addresses are blocked. Remove an entry at any time to revoke it.

🔐 Two-Factor Authentication

Enable TOTP-based 2FA and manage recovery codes here — see Account Security for the step-by-step.

💻 Active Sessions

Every browser/device you sign in from creates a session. Review the list and sign out of all other sessions if a device is lost or you see activity you don't recognize.

🎨 Branding

Personalize the portal for your organization (or your customers, on white-label plans): upload a logo and favicon, and set brand colors. The branding is applied across the portal UI.

👤 SCIM Provisioning

Automate user lifecycle from your identity provider (Okta, Azure AD, etc.) using SCIM 2.0. Generate a SCIM bearer token here, then point your IdP's SCIM connector at the portal's SCIM endpoint. Users and groups are then created, updated, and deprovisioned automatically. Delete a token to immediately cut off that connector.

🔗 Single Sign-On (SSO)

Configure SAML or OIDC SSO so your team logs in through your identity provider. Enter your IdP details under SSO config, use Test to validate the connection before enforcing it, and remove the config to disable SSO.

🔑 SSH Key Upload

Upload public SSH keys to be auto-provisioned to Linux devices — see Groups, SSH & API Keys.

🎫 Zero-Touch Provisioning

Create and manage provisioning tokens for hands-off device enrollment — see Zero-Touch Provisioning.

💳 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.