Documentation

Getting Started

To connect a machine to Interveon, you'll need two things: an account on the server and the thin client running on the machine you want to connect.

Requirements

The Interveon client requires Node.js 22 or later. Install it from nodejs.org, or use your preferred method (nvm, fnm, Homebrew, apt, etc.).

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
nvm use 22
node --version  # should show v22.x.x or later

Remote desktop requires ffmpeg, which the thin client downloads automatically on first run. No manual installation needed — a native binary for your platform is fetched and stored in ./bin/ffmpeg next to the client script.

1. Create an Account

Ask your server administrator for an invite, or sign up if registration is open. Once you have an account, log into the admin panel to find your workspace token — you'll need this to connect your client.

Your workspace token and server URL are all the client needs to authenticate. You can find both in the admin panel under Workspace Tokens.

2. Download & Run the Client

The Interveon client is a single JavaScript file. Download it and run it with Node.js — no other dependencies required.

curl -O https://interveon.com/downloads/interveon-client.js

node interveon-client.js

That's it. The client starts a local dashboard where you can configure everything through your browser.

3. The Client Dashboard

Once the client is running, open the local dashboard:

http://127.0.0.1:7700

From the dashboard you can:

• Connect to a server — enter the server URL and your workspace token
• Create tunnels — expose local ports with a name (e.g. "myapp" on port 3000)
• Enable remote access — toggle remote terminal, desktop, and file sharing on or off
• Configure TURN (optional) — add your own TURN relay server if peer-to-peer connections don't work on mobile or VPN networks

All settings are saved locally and persist across restarts. You can also configure everything via CLI flags if you prefer.

CLI Options

Everything available in the dashboard can also be set via command-line flags:

node interveon-client.js [options]

  --host <url>           Server URL (e.g. https://interveon.com)
  --token <token>        Workspace authentication token
  --expose <name>:<port> Expose a local port as a tunnel (repeatable)
  --headless             Run without the local dashboard
  --port <port>          Dashboard port (default: 7700)

  Feature flags:
  --allow-terminal       Enable remote terminal access (default: on)
  --allow-desktop        Enable remote desktop access (default: on)
  --allow-files          Enable file sharing (default: on)

  TURN relay (optional):
  --turn-url <url>       TURN relay server URL
  --turn-user <user>     TURN username
  --turn-pass <pass>     TURN password

  Background service:
  --install              Install as a background service (starts on boot)
  --uninstall            Remove the background service
  --restart              Restart the background service

Expose format: --expose myapp:3000 proxies to localhost, --expose nas:192.168.1.10:8080 proxies to a LAN device, and appending +tls connects to the upstream over TLS.

Running in the Background

After configuring your tunnels through the dashboard, install the client as a system service that starts automatically on boot:

node interveon-client.js --install

This creates a native service for your platform — launchd on macOS, systemd on Linux, or Task Scheduler on Windows. The client and ffmpeg are copied to ~/.interveon/ so you can safely delete the original download. The dashboard remains available at http://127.0.0.1:7700.

Logs rotate automatically at 5 MB and are stored at:

macOS:   ~/Library/Logs/Interveon/interveon.log
Linux:   ~/.local/share/interveon/interveon.log
Windows: %APPDATA%\Interveon\interveon.log

To remove:

node interveon-client.js --uninstall

Architecture

Interveon consists of two components:

• Server — the relay that accepts tunnel connections and proxies traffic. Runs on a VPS with a public IP and domain.
• Client — a single-file Node.js script that runs on any machine you want to connect. Creates outbound connections to the server — no inbound ports needed.

All tunnel traffic flows through the relay server. Remote desktop uses WebRTC for peer-to-peer video on WiFi and LAN networks. For restrictive networks (mobile 5G, VPNs, strict firewalls), the system automatically falls back to HTTP frame relay — JPEG frames over TCP through the existing relay infrastructure.

Browser Features

Once connected, the admin panel at interveon.com gives you access to:

• File Manager — browse, upload, download, preview (images, video, audio, text), search, and share files. Streaming transfers of any size with auto-resume. Drag & drop and folder upload. Create public share links with expiry.
• Request Inspector — real-time view of HTTP requests flowing through your tunnels. Filter by method, status code, or tunnel. Click any request for full headers and timing.
• Analytics — request volume, bandwidth, response time percentiles (p50/p95/p99), status code distribution, top paths and IPs. Filter by tunnel and date range.
• Access Policies — protect tunnels with IP whitelists, blacklists, and password authentication per tunnel.
• API Keys — generate API keys for programmatic access. Authenticate with Authorization: Bearer ivn_... on any API endpoint.
• Session Management — view active sessions across devices, revoke individually or all at once.
• Short Links — create branded short URLs that redirect through your tunnels, with click analytics.
• Webhooks — receive POST notifications when tunnels connect/disconnect. Configure in Settings with optional HMAC signing for verification.
• Rate Limiting — set requests-per-minute limits per tunnel or per plan. Exceeding the limit returns HTTP 429.

Mobile and VPN Access

Remote desktop uses WebRTC peer-to-peer video on WiFi and LAN. On mobile networks (4G/5G) and VPNs, symmetric NAT blocks P2P connections. Interveon handles this automatically with a three-tier fallback:

• P2P — tried first, works on WiFi/LAN, zero server bandwidth
• TURN relay — WebRTC through an embedded TURN server (requires VPS with open UDP)
• HTTP relay — JPEG frames over TCP, works through any firewall or carrier

The browser tries P2P first. The client signals its capture state through the data channel, and the browser starts a short video timer only after RTP packets are flowing. If the connection can't deliver video, it silently switches to HTTP relay. No user configuration needed — it just works.

Windows note: Screen capture and input are unavailable when the Windows lock screen or UAC prompt is active. This is a Windows Secure Desktop restriction that affects all third-party remote desktop tools at the application level. The desktop resumes automatically when the user logs back in.

Embedded TURN server (optional)

For lower-latency relay on a VPS with UDP support, enable the embedded TURN server in Settings → Remote Desktop. This provides a middle tier between P2P and HTTP relay. Requires UDP port 3478 open in your firewall.

Dependencies

The thin client automatically downloads the latest release of ffmpeg on first run — no package managers or manual installation needed. The binary is stored in ./bin/ffmpeg next to the client script and used for all screen capture operations.

Desktop Control Modes

Each tunnel has a configurable control mode (click the mode button next to the 🖥️ toggle in the tunnel list):

• Shared — all viewers can control the desktop simultaneously (default)
• View Only — only the first viewer has input control; additional viewers watch
• Takeover — one controller at a time, but any viewer can click "Take Control" in the toolbar to take over

You can also use an external TURN server like coturn:

sudo apt install coturn

# Edit /etc/turnserver.conf:
realm=interveon.com
listening-port=3478
external-ip=YOUR_VPS_PUBLIC_IP
user=interveon:pick-a-strong-password
lt-cred-mech
no-tls

sudo systemctl enable coturn
sudo systemctl start coturn

Then in Interveon Settings → Remote Desktop, fill in:

• TURN URL: turn:YOUR_VPS_IP:3478
• Username: interveon
• Credential: your chosen password

Ensure UDP port 3478 is open in your firewall. TURN is only used as a middle tier — WiFi connections always go direct P2P, and HTTP relay handles everything else.

Permissions

Remote access features (terminal, desktop, file sharing) are controlled at four independent levels:

• Global — server-wide enable/disable in the admin settings
• Workspace — granted per workspace by the admin
• Tunnel — toggled per tunnel on the tunnels page
• Client — the machine owner opts in via the local dashboard

All four levels must be enabled for a feature to work. This ensures that both the server administrator and the machine owner have explicitly consented.

Backup & Restore

Interveon supports encrypted backup archives (.ivnk files) containing both databases, configs, and all workspace data. Backups are encrypted with AES-256-GCM — you set the passphrase, and without it the archive is unreadable.

Sensitive credentials (backup passphrase, SFTP password, SFTP private key) are stored encrypted in the config file using AES-256-CBC with an auto-generated key. Existing plaintext credentials are automatically encrypted on next save.

Configure in Settings → Backup & Restore:

• Manual backups — click "Run Backup Now" with your passphrase
• Scheduled backups — hourly or daily at a custom time with automatic retention and timezone-aware scheduling
• Selective restore — inspect a backup to see its workspaces and users, then restore only what you need
• Cross-server restore — copy an .ivnk file to any Interveon install and restore from there
• SFTP remote upload — automatically upload backups to a remote SFTP server for off-site disaster recovery (password or private key auth)

Database snapshots use SQLite's VACUUM INTO for atomic captures with no downtime. Selective restores merge into the live database immediately — no restart needed.