Welcome to Xaccel IoT

Xaccel IoT is a secure remote access and management platform for your IoT devices, servers, Raspberry Pis, industrial computers, and any Linux-based machine — no matter where in the world they are located.

Once you install a small agent on your device, it connects back to the Xaccel IoT platform over an encrypted tunnel. From that point on, you can access your device from any browser, anywhere, without needing to open firewall ports, configure VPNs, or know the device's IP address.

Your portal is accessed through a web browser. Your account administrator will have provided you with the portal URL, your email address, and a temporary password.

The Dashboard is the first thing you see after logging in. It gives you an at-a-glance view of your entire device fleet.

To connect a device to Xaccel IoT, you need to do two things: register it in the portal to get a unique device token, then install the agent on the device itself using that token.

SSH into your device (or use a local terminal) and run the one-line install command shown in your portal under Settings → Install Command. It looks like this — with your Setup Key and portal URL already filled in:

The installer will automatically download the agent, install Node.js if needed, configure it with your Setup Key, and start it as a system service that automatically restarts on reboot.

After installing the agent, go back to the Devices page in the portal. Within about 30 seconds, your device should appear with a ● Online status. If it shows as offline after a minute, see the Troubleshooting section.

The Devices page lists all devices registered to your account. You can search, filter by status or group, and click any device to open its detail panel.

Click on any device to open its detail panel on the right side of the screen. This panel has several tabs:

The Web Console gives you a full, interactive SSH terminal session to any online device — directly in your browser. No SSH client, no keys to configure, no VPN required.

SSH Tunnels let you access services running on your remote device as if they were running on your local computer. For example, you can access a web interface running on port 8080 of your device by opening http://localhost:8080 in your browser.

This is useful for accessing device dashboards, databases, APIs, or any other service that listens on a port — without exposing those ports to the internet.

If your device runs a web interface (like a router admin page, Node-RED, Grafana, or a custom dashboard) on port 80 or 443, you can access it directly in your browser — no SSH command needed.

When you create a tunnel with remote port 80 or 443, the portal automatically opens the device's web UI in a new browser tab via a secure reverse proxy. The URL is authenticated with a short-lived token so only you can access it.

If your device runs a VNC server (for a graphical desktop), you can view and control it directly in your browser — no VNC client app required. The portal includes a built-in VNC viewer powered by noVNC.

You can view and control an Android device’s screen in your browser using the VNC tunnel feature. The Xaccel IoT agent automatically installs DroidVNC-NG when it detects it is running on Android via Termux — no manual Play Store installation needed.

Instead of typing a password every time you open a console session, you can save your SSH private key in the portal. The key is stored securely and used automatically when you connect to devices.

If you don't have an SSH key yet, you can generate one on your local machine:

Xaccel IoT continuously collects system metrics from every connected device. You can view live data and historical charts to understand device health and performance over time.

Alerts automatically notify you by email when a device goes offline or when a metric (CPU, memory, disk) exceeds a threshold you define. You can set up alerts per device or globally for all devices.

Batch Jobs let you run a shell command or script on one or many devices simultaneously. This is ideal for software updates, configuration changes, service restarts, or any task you'd normally have to do device by device.

After a job runs, you can see the output from each device in the job results panel. Each device shows a ✓ Success or ✗ Failed status along with the full command output. Job history is saved so you can review past runs at any time.

The File Upload feature lets you push files from your computer to one or many remote devices. This is useful for deploying configuration files, scripts, firmware updates, certificates, or any other file your devices need.

If you are a Tenant Admin, you can invite other people to your account and control what they can access. Each person gets their own login and can be assigned a role that limits their permissions.

From the Users tab, you can change a user's role, reset their password, or remove them from your account. Removing a user immediately revokes their access — they will not be able to log in.

Groups let you organize your devices into logical categories — for example by location, function, customer, or environment. Once grouped, you can filter the device list, run batch jobs, and upload files to an entire group at once.

The Billing page lets you view your current plan, see your device usage, manage your payment method, and download invoices. Only Tenant Admins can access billing.

Click Billing in the left navigation menu. You'll see your current plan, usage summary, and billing history.

All invoices are listed in the Invoice History section of the Billing page. Each invoice shows the date, amount, and status. You can click any invoice to view the full details or download it as a PDF. If an invoice is marked Failed, you can click Pay Now to retry the payment.

Two-factor authentication adds an extra layer of security to your account. Once enabled, you'll need both your password and a 6-digit code from an authenticator app to log in.

After entering your email and password, a second screen will appear asking for your 6-digit code. Open your authenticator app, find the Xaccel IoT entry, and enter the current code. Codes refresh every 30 seconds.

Xaccel IoT uses PostgreSQL as its production database. PostgreSQL provides the reliability, performance, and scalability needed for large device fleets. SQLite is available for local development only.

Automatic Installation

The install script automatically:

• Installs PostgreSQL 16 from the official repository
• Creates the xaccel_iot database and xaccel user
• Generates a secure random password
• Configures firewall rules to block external database access
• Writes the connection string to your .env file

Connection Settings

Your database connection is configured in /opt/xaccel-iot/.env:

DB_DRIVER=postgres
DATABASE_URL=postgresql://xaccel:YOUR_PASSWORD@localhost:5432/xaccel_iot

Migrating from SQLite

If you have an existing Xaccel IoT installation using SQLite and want to move to PostgreSQL:

1. Set up PostgreSQL and update your .env with the DATABASE_URL
2. Run a dry-run first to check for issues:

   DRY_RUN=true node migrate-sqlite-to-postgres.js

3. If the dry-run looks good, run the actual migration:

   node migrate-sqlite-to-postgres.js

4. Restart the application: pm2 restart xaccel-iot

Backup & Restore

A backup script is installed automatically at /usr/local/bin/xaccel-db-backup. It creates a compressed PostgreSQL dump in /var/backups/xaccel-iot/.

Manual backup

/usr/local/bin/xaccel-db-backup

Restore from backup

gunzip -c /var/backups/xaccel-iot/xaccel_iot_YYYY-MM-DD.sql.gz | sudo -u postgres psql xaccel_iot

Automated daily backups

The install script sets up a daily cron job at 2:00 AM that runs the backup automatically and retains the last 7 days of backups.

Useful Database Commands

Performance Tips

• For fleets over 500 devices, increase max_connections in postgresql.conf
• Enable pg_stat_statements to identify slow queries
• Run VACUUM ANALYZE periodically on high-write tables like metrics_history and device_logs
• Consider partitioning metrics_history by month for very large deployments

Scheduled Jobs let you run any command across one device, a group, or all devices on a recurring schedule — without you having to be online. Think of it as a cron job that runs across your entire fleet.

Creating a Scheduled Job

1. Go to Jobs in the left navigation
2. Click the Scheduled tab
3. Click + New Schedule
4. Fill in the name, command, target (all devices, a group, or a specific device), and schedule
5. Use the cron builder or type a cron expression directly
6. Click Save

Cron Schedule Examples

Targets

• All devices — runs on every device in your account
• Group — runs on all devices in a specific group
• Single device — runs on one specific device

Viewing Results

Each scheduled job shows its Next Run, Last Run, and Last Status (success / failed / running). Click a job to see the full output of the last run. You'll also receive an alert notification when a scheduled job completes or fails.

The Log Viewer aggregates logs from all your devices into a single searchable interface. No more SSH-ing into each device to check logs — everything is in the portal.

Accessing the Log Viewer

Click Logs in the left navigation. You'll see a live stream of log entries from all online devices.

Filtering Logs

• Device — filter to a specific device
• Level — filter by severity: debug, info, warning, error, critical
• Source — filter by log source: journald, syslog, or custom log files
• Search — full-text search across all log messages
• Time range — view logs from a specific time window

Live Tail

Toggle Live Tail to see new log entries appear in real time as they arrive from your devices — similar to tail -f but across your whole fleet.

Exporting Logs

Click Export to download the current filtered view as a CSV file. Useful for incident reports or compliance audits.

Log Sources

The agent automatically collects from journald (systemd logs) and syslog. You can configure additional custom log files in the agent config.

Enterprise accounts can fully customise the portal with your company's logo, colours, and domain name. Your customers see your brand, not Xaccel.

Setting Up Branding

1. Go to Settings → White-Label Branding
2. Upload your logo (PNG or SVG recommended)
3. Upload your favicon (ICO or PNG, 32×32px)
4. Set your primary colour using the colour picker
5. Enter your company name (shown in the browser tab title)
6. Optionally add custom CSS for advanced styling
7. Click Save Branding

Custom Domain

To serve the portal from your own domain (e.g. portal.yourcompany.com):

1. Point your domain's DNS CNAME record to your Xaccel server IP
2. Enter the domain in the Custom Domain field in Branding settings
3. Your server admin updates the Nginx config and issues a TLS certificate

Live Preview

Click Preview to see your branding applied instantly without saving. This lets you experiment with colours and logos before committing.

SCIM 2.0 lets your identity provider (IdP) automatically create, update, and deactivate user accounts in the portal. When you add someone to the right group in Okta or Azure AD, they get portal access automatically — and when you remove them, access is revoked immediately.

Setting Up SCIM

1. Go to Settings → SCIM Provisioning
2. Click + New Token to create a bearer token
3. Copy the token — it will only be shown once
4. Note the SCIM Base URL shown on the page
5. In your IdP, configure SCIM with:
   • Base URL: the URL shown in the portal
   • Authentication: Bearer token (paste the token you copied)

What Gets Synced

Supported Identity Providers

• Okta — use the SCIM 2.0 app template
• Azure AD / Entra ID — use Enterprise Application → Provisioning
• Google Workspace — use a custom SCIM connector
• Any IdP supporting SCIM 2.0 (RFC 7644)

Beyond the built-in CPU, memory, and disk metrics, you can define your own custom metrics — anything your device can output from a shell command. Temperature sensors, queue depths, application counters, battery levels — if a script can print it, you can chart it.

Creating a Custom Metric

1. Go to Metrics in the left navigation
2. Click + New Metric
3. Enter a name and optional unit (e.g. °C, MB, req/s)
4. Write a shell collector command — a command that prints a single number
5. Set the collection interval (how often to run the command)
6. Optionally set a threshold alert (e.g. alert if value exceeds 80)
7. Click Save

Collector Command Examples

Viewing Charts

The Metrics dashboard shows a time-series chart for each custom metric across all devices. You can filter by device, change the time range, and see threshold lines on the chart.

Threshold Alerts

Set a threshold value and operator (greater than, less than, equals). When a device's metric crosses the threshold, you receive an alert notification via email or push notification.

Remote Power Control lets you reboot or shut down any device directly from the portal — no SSH session required. This is especially useful when a device is unresponsive or you need to apply changes that require a restart.

Using Power Control

1. Open a device's detail page
2. Click the ⚡ Power button in the device header
3. Choose an action:
   • Reboot — graceful restart via systemctl reboot
   • Shutdown — graceful power off via systemctl poweroff
   • Hard Reboot — immediate kernel-level reboot (use only if the device is unresponsive)
4. Optionally set a delay (0–300 seconds) before the action executes
5. Click Confirm

Power History

The Power Control card on the device detail page shows the last 10 power events — action taken, who triggered it, timestamp, and status.

Permissions

Power control requires the Admin role. Regular users cannot trigger power actions.

If you've checked this guide and the troubleshooting section and still need help, here's how to reach us: