PiDOC Usage Guide

Install, monitor, and securely access your devices from anywhere — all in one place.

1. Installation

Run the following command in your device's terminal:

bash
$ curl -fsSL https://dl.piops.net/pidoc/inst.sh | bash

Verify the installation:

$ pidoc version
PiDOC v2.0.11

Installing a Specific Version

You can pin a specific version. If the device already has PiDOC installed, the specified version must not be lower than the current one. Example for v2.0.11:

$ PIDOC_VERSION=2.0.11 bash <(curl -sSL https://dl.piops.net/pidoc/inst.sh)

Browse all versions and architectures at dl.piops.net/pidoc/.

2. Features

Core Features

  • ▸ Real-time Monitoring — CPU load, network, disk, temperature
  • ▸ Web Terminal — Secure SSH access from anywhere in the world
  • ▸ Web SFTP — Browse, upload, and download files via a web-based file manager
  • ▸ Web VNC — Remote desktop access directly from your browser
  • ▸ Web Forwarding — Expose device HTTP services (Home Assistant, OpenClaw, etc.) via custom subdomains
  • ▸ Bastion SSH — Two-layer SSH proxy for secure tunneling
  • ▸ Local Forwarding — Map remote device ports to localhost for VNC, game servers, etc.

All features are provided free of charge. Resources are shared, so please use them responsibly.

3. Registration

Go to ops.piops.net and sign up for a free account.

Registration requires a valid email address. After signing up you will receive a verification email — click the "Verify Email" button or copy the link into your browser to complete verification.

Once verified, you can log in and start adding devices.

4. Adding Devices

  1. 1 Navigate to the Device Management page.
  2. 2 Click the Add button to generate a new device key.
  3. 3 Copy the generated command and run it on your device. If the device already has PiDOC installed, run:
$ sudo pidoc service install <your-device-key>

Once connected, the device will appear in your Device Management list with a green online indicator.

Device Alias

Each new device is assigned an auto-generated alias based on its type and serial number — Raspberry Pi devices get an rpi- prefix, Orange Pi devices get opi-. For example, a Pi with serial 123456789 will appear as rpi-123456789.

You can customize the alias by clicking the pencil icon next to the device name. Use a name that helps you identify the device easily. Each alias must be unique — it is used as a host identifier when connecting via bastion SSH.

5. Metrics Monitoring

The monitoring dashboard provides real-time metrics for each device:

  • ▸ System — Uptime
  • ▸ CPU — Load average and temperature
  • ▸ Memory — Total and used
  • ▸ Disk — Usage percentage and read/write IO
  • ▸ Network — Packets and bytes (sent/received)

Switch between devices using the top-left selector and adjust the time range on the right.

6. Web Remote Access

Click Remote Access in the sidebar to open a new browser window. The following access methods are available:

SSH Terminal

Click the + tab or New Connection, then select SSH Terminal. Enter your device's SSH username, port, and choose between password or private key authentication.

SFTP File Manager

Click the + tab or New Connection, then select SFTP File. Enter your device's SSH credentials. Once connected you can browse directories, multi-select files, drag-and-drop uploads, and download files.

VNC Desktop

Click the + tab or New Connection, then select VNC Desktop. Enter the VNC port (default: 5900). If the VNC service is running and reachable, you will be prompted for username and password. If it fails, verify the VNC service is active and the port is correct.

7. Bastion SSH (ProxyJump)

Bastion SSH lets you use native SSH tools — scp for file transfer, VS Code Remote SSH for development, or any IDE that supports SSH — through an encrypted proxy tunnel.

Creating a Bastion Key

  1. 1 Go to Key Management in the sidebar navigation.
  2. 2 If you already have an SSH key pair, paste your public key directly. Otherwise, click Create Key to generate a new ED25519 key pair.

Important: Download and securely store your private key immediately. It cannot be retrieved after the download window closes. Place it in your ~/.ssh/ directory (%USERPROFILE%\.ssh\ on Windows).

SSH Config Setup

The bastion host is ops.piops.net:64422. Your target device is identified by its alias (the first column in Device Management).

On Windows, create or edit %USERPROFILE%\.ssh\config. First, ensure the directory exists:

PowerShell
PS> # Create .ssh directory if needed, then open config
if (-not (Test-Path "$env:USERPROFILE\.ssh")) { New-Item -Path "$env:USERPROFILE\.ssh" -ItemType Directory -Force | Out-Null }; notepad "$env:USERPROFILE\.ssh\config"

Example SSH config — replace rpi-5 with your device alias, and pi with your device username:

~/.ssh/config
# Target device (use alias from Device Management)
Host rpi-5
    User pi
    Port 22
    IdentityFile ~/.ssh/id_rsa
    ProxyJump ops.piops.net

# Bastion proxy host
Host ops.piops.net
    Port 64422
    IdentityFile ~/.ssh/id_ed25519_bastion

Connecting

$ ssh rpi-5

On first connection you may see a host key warning — type yes to continue. If you need to debug, use ssh -v rpi-5.

Multiple Devices (Wildcard)

Use SSH config wildcards to avoid repeating settings for each device:

~/.ssh/config
# Match all devices with the same prefix
Host rpi-*
    User pi
    Port 22
    IdentityFile ~/.ssh/id_rsa
    ProxyJump ops.piops.net

Host ops.piops.net
    Port 64422
    IdentityFile ~/.ssh/id_ed25519_bastion

SCP File Transfer

# Copy local file to remote device
$ scp ./localfile.txt rpi-5:/home/pi/

# Copy remote file to local
$ scp rpi-5:/home/pi/remotefile.txt ./

VS Code Remote Development

Install the Remote - SSH extension. After installation, open the Remote Explorer sidebar, find your device, and click the connect arrow. VS Code will open a new window connected to your remote device.

This also works with any IDE or terminal that supports SSH config files, including JetBrains IDEs, MobaXterm, and the built-in Windows Terminal.

8. Local Port Forwarding

Local port forwarding maps a remote device's port to your local machine, enabling VNC connections, Minecraft servers, and other TCP-based applications. This feature requires the PiDOC Desktop client.

Download: PiDOC Desktop Win64 v0.1.2

Client Login

  1. 1 Go to ops.piops.net and generate an Agent Token from the Key Management page.
  2. 2 Launch PiDOC Desktop and paste your token to log in. Your device list will appear.

VNC Forwarding Example

Add a new forwarding rule in the port forwarding panel. Set the target port to 5900 (default VNC port). Click the arrow to start the rule, then connect your VNC client to localhost:5900.

SSH Forwarding Example

Since low-numbered ports may be reserved locally, set the source port to 60022 and the target port to 22. After starting the rule, connect with ssh localhost -p 60022.

9. Web Forwarding

If you run web applications on your devices — such as OpenClaw, Home Assistant, or any HTTP service — you can expose them via the web forwarding feature.

Configure a forwarding route in the Forwarding section at ops.piops.net, specifying your device, port, and a custom subdomain.

Web forwarding requires an active login session at ops.piops.net. The session must be valid for forwarded content to load.

10. Configuration

The PiDOC configuration file is located at /etc/pidoc/config.json. It is auto-generated when you run pidoc service install.

A standard install produces a minimal config with just the private key:

/etc/pidoc/config.json
{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds="
}

Advanced features can be enabled by manually editing the config file:

Field Type Description Since
private_key string Device key generated from the management console (Device Management → Add). v2.0.0
server_addr string Proxy server address. Default: ops.piops.net:3322. Omit to use default. v2.0.7
websocket boolean Enable WebSocket transport for firewall traversal. v2.0.6
websocket_url string WebSocket endpoint URL. Default: wss://ops.piops.net/ws. v2.0.7
forward_port_whitelist array of int Port whitelist for local forwarding. Restrict forwarding to specific ports for security. v2.0.7
client_id string Custom client ID (optional; auto-detected from device serial if empty). Must be unique per account. v2.0.8

Full configuration example:

/etc/pidoc/config.json
{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds=",
  "server_addr": "ops.piops.net:3322",
  "websocket": true,
  "websocket_url": "wss://ops.piops.net/ws",
  "forward_port_whitelist": [22, 5900],
  "client_id": "my-custom-client-id"
}

11. Troubleshooting

If you encounter issues, check the following:

  1. 1. Verify the device SSH service is running and the port is correct
  2. 2. Log in to ops.piops.net — is the device showing online (green indicator)?
  3. 3. Click the device for details — confirm the SSH port is correct
  4. 4. Is the sshd service running on the device?

Run these commands on your device to diagnose:

$ sudo systemctl status ssh
$ sudo netstat -tlnp | grep 22

If the issue persists, check the PiDOC client agent on the device:

$ sudo systemctl status pidoc
$ ps aux | grep -i pidoc
$ sudo netstat -tnp | grep 64422
$ sudo ss -tnp | grep pidoc
$ sudo systemctl restart pidoc

12. Compatibility

Supported Hardware

Device Debian 12 Debian 13 Ubuntu 22 Ubuntu 24 Armbian 25
Raspberry Pi 5✓✓✗✓✓
Raspberry Pi 4✓✓✓✓✓
Raspberry Pi 3✓✓✓✓✓
Orange Pi CM4——✓—✓
NanoPi R4S————✓

Supported Architectures

arm64 armhf amd64 i386 riscv64 loong64

Supported Operating Systems

Raspberry Pi OS, Debian, Ubuntu, Armbian, Kali Linux, Linux Mint, Kylin, UOS, Deepin, and other Debian-based distributions.

Note: The devices and OS versions listed above have been verified through actual testing. Your device may work even if not explicitly listed, as long as it meets the architecture requirements. Ubuntu 22.04 does not support Raspberry Pi 5 (Ubuntu added Pi 5 support starting from 23.10). ✓ = Supported | ✗ = Not supported | — = Untested

13. Security

Architecture Overview

PiDOC is a three-layer SSH tunnel architecture for NAT traversal and remote access:

  1. 1. PiDOC Client — installed on your device
  2. 2. PiDOC Proxy — relay server deployed on the public internet
  3. 3. User Terminal — SSH client, Web SSH, or PiDOC Desktop

Three-Layer Encryption

  • ▸ Layer 1: PiDOC ↔ Proxy (ED25519 public-key auth + SSH encryption)
  • ▸ Layer 2: User ↔ Proxy (multi-auth + SSH encryption)
  • ▸ Layer 3: Proxy ↔ Target SSH (transparent forwarding)

Security Properties

  • ✓ End-to-end SSH encryption — all data encrypted at the SSH protocol layer
  • ✓ Public-key authentication — passwords never transmitted over the network
  • ✓ Key binding — each device uses a unique key, preventing impersonation
  • ✓ Dual encryption (Web mode) — TLS + SSH protocol stack
  • ✓ User isolation — each user can only access their own devices

Why Is It Secure?

  • ▸ No single point of decryption — the proxy only routes traffic, it cannot decrypt user SSH sessions
  • ▸ Zero-trust architecture — each layer requires independent authentication and encryption
  • ▸ Private key never leaves the device — keys remain on the endpoint locally
  • ▸ Standard protocols — built on OpenSSH, battle-tested over decades

14. Uninstall

To remove PiDOC from your device:

$ sudo apt remove pidoc

Ready to get started?

Open Ops Console →