Documentation

Overview

OnOffMyPC lets you remotely control your desktop PC's power state — turn it on, off, reset, or force-power-cycle it — from anywhere in the world using our web app, Android app, or any browser.

There are two ways to connect your PC:

• Desktop Agent (Software): A lightweight background process for Windows and Linux. It handles OS-level power actions (restart, shutdown, sleep, lock, log out) and reports real-time diagnostics (CPU, RAM, disk, temperature).
• ESP32 / ESP8266 Hardware: A microcontroller wired directly to your motherboard's front-panel headers. It can physically toggle the power switch and reset button even if the operating system has crashed, frozen, or failed to boot.

Quick start

1. Create an account at app.onoffmypc.com and verify your email.
2. Add a device in the dashboard. Give it a name — you will receive a short pairing code.
3. Connect your PC — either install the Desktop Agent (see Desktop Agent setup) or flash your ESP32/ESP8266 (see Hardware setup), then enter the pairing code.
4. Send your first command from the dashboard or the Android app.

The whole flow takes under five minutes for the software path, or around 15–20 minutes if you are also wiring hardware.

Account setup

Registration

Sign up at app.onoffmypc.com/register.html with your email address. A verification link will be sent to your inbox — you must verify your email before adding devices.

Email verification

Open the email from OnOffMyPC and click the verification link. If it does not arrive within a few minutes, check your spam folder. You can request a new link from the onboarding checklist on the dashboard.

Password reset

Use the Forgot password link on the login page. A reset link is emailed immediately and expires after one hour.

Desktop Agent (Software)

The Desktop Agent is a lightweight background service that connects your PC to the OnOffMyPC relay over an outbound WebSocket. No port forwarding or firewall rules are required.

Windows installation

1. Download the latest OnOffMyPC-Setup.exe from the releases page.
2. Run the installer. It installs the agent as a Windows Service and places a tray icon in the system tray.
3. The tray icon will prompt for a pairing code. Enter the code displayed in your dashboard device page.
4. The agent authenticates once and then runs silently in the background, starting automatically on every boot.

Uninstalling

Open Add or Remove Programs, find OnOffMyPC Agent, and click Uninstall. The Windows Service and tray icon are removed automatically.

Linux installation

1. Download the latest onoffmypc-agent_linux_amd64.tar.gz from the releases page.
2. Extract and run the installer script:

   tar -xzf onoffmypc-agent_linux_amd64.tar.gz
   cd onoffmypc-agent
   sudo ./install.sh

3. The installer registers a systemd service. Start it:

   sudo systemctl start onoffmypc-agent
   sudo systemctl enable onoffmypc-agent

4. Enter your pairing code when prompted, or pass it directly:

   sudo onoffmypc-agent pair --code YOUR_PAIRING_CODE

Viewing logs

journalctl -u onoffmypc-agent -f

Agent configuration

The agent stores its configuration in:

• Windows: %APPDATA%\OnOffMyPC\config.json
• Linux: /etc/onoffmypc/config.json

Supported commands (Desktop Agent)

Telemetry reporting

The agent sends periodic telemetry reports to the relay, which are surfaced in the dashboard and mobile app:

• CPU usage (%)
• RAM usage (%)
• Disk usage (%)
• CPU temperature (°C, where available)
• System uptime
• Agent version and platform
• Public IP (for informational display only)

Telemetry is sent every 30 seconds by default. You can adjust this with the telemetry_interval_s config option.

ESP32 / ESP8266 Hardware Integration

The hardware path wires a small microcontroller directly to your motherboard's front-panel header. It lets you:

• Physically press the power button to turn on a machine that is fully off
• Trigger a hardware reset even if the OS has frozen or crashed
• Perform a force power-cycle (hold power button) when the OS is completely unresponsive
• Report ambient temperature and humidity (DHT sensor, optional)
• Report WiFi signal strength (RSSI)

Requirements

• An ESP32 or ESP8266 development board (common options: ESP32-DevKitC, NodeMCU v3, Wemos D1 Mini)
• A USB cable for initial flashing (Micro-USB or USB-C depending on the board)
• Access to the front-panel header on the motherboard (power switch, reset switch, power LED)
• A 2.4 GHz WiFi network within range of the PC's case
• Google Chrome or Microsoft Edge for the browser-based flasher

No soldering is required for most builds — standard Dupont jumper wires fit directly on the 0.1-inch header pins.

Wiring guide

Locate the front-panel header on your motherboard (usually in the bottom-right corner, labelled F_PANEL or JFP1). The pins to use are:

For a visual wiring diagram, see the setup guide wiring section.

Flashing firmware

1. Open onoffmypc.com/setup.html in Chrome or Edge.
2. Connect your ESP32/ESP8266 board to your computer via USB.
3. Click Flash firmware and select your board type (ESP32 or ESP8266) from the dropdown.
4. Your browser will ask for port access — select the correct COM port (Windows) or /dev/ttyUSB0 (Linux).
5. Wait for the flash to complete (around 30–60 seconds). The board will restart automatically.

The flasher uses the Web Serial API — no drivers or toolchain are required. Only Chrome and Edge support Web Serial.

Pairing a device

1. After flashing, the ESP32/ESP8266 will broadcast its own WiFi setup hotspot for 5 minutes.
2. Connect to it from your phone or laptop and enter your home WiFi credentials via the captive portal.
3. The board joins your network and shows a pairing code on its serial output (or on its display, if attached).
4. In the OnOffMyPC dashboard, click Add device → Hardware device, then enter the pairing code shown by the board.
5. The device appears in your dashboard within seconds.

Supported commands (Hardware)

Combined setup

You can register both a hardware device and a software agent for the same physical machine. They appear as two separate devices in the dashboard (each with its own name and pairing code). This gives you:

• Hardware turn-on via the ESP32 when the machine is off or frozen
• Graceful OS actions (restart, sleep, lock) via the software agent once the machine is running
• Redundant monitoring — the dashboard can show both hardware telemetry (room temperature, RSSI) and OS telemetry (CPU, RAM)

In the dashboard, you can rename each device to make it clear which is hardware and which is software (for example: Home PC – Hardware and Home PC – Software).

API overview

OnOffMyPC exposes a REST and WebSocket API used by the web dashboard, mobile apps, and device agents. All REST endpoints are under https://api.onoffmypc.com and require a valid session token in the Authorization: Bearer <token> header.

Authentication endpoints

Device endpoints

Command endpoints

Telemetry endpoint

Telemetry payload

Devices and agents POST a JSON payload to /telemetry/:deviceId. Fields are optional — send only what your hardware supports.

{
  "pc_state": "on",           // "on" | "off" | "unknown"
  "temperature_c": 24.5,      // Ambient temperature (DHT sensor)
  "humidity_pct": 45.2,       // Ambient humidity (DHT sensor)
  "rssi": -62,                // WiFi signal dBm (hardware devices)
  "cpu_pct": 18,              // CPU usage % (software agent)
  "ram_pct": 54,              // RAM usage % (software agent)
  "disk_pct": 72,             // Disk usage % (software agent)
  "cpu_temp_c": 51.3,         // CPU temperature °C (software agent)
  "uptime_s": 86400,          // System uptime in seconds
  "agent_version": "1.2.0",   // Agent or firmware version string
  "platform": "windows"       // "windows" | "linux" | "esp32" | "esp8266"
}

Command types

Device states

The dashboard displays the PC power state separately from the device connection state. A device can be online (the agent is connected) while the PC state is off (the agent is reporting the machine as powered off from an OS perspective).

FAQ

Do I need to open firewall ports?

No. Both the Desktop Agent and the ESP32 firmware make outbound WebSocket connections over port 443 (HTTPS/WSS). No inbound ports need to be opened and no port forwarding is required.

Can I wake a machine over the internet without hardware?

Not if it is fully powered off and you only have the software agent — the agent requires the OS to be running. The ESP32/ESP8266 hardware device can send a physical power-on pulse to the motherboard regardless of OS state, enabling true remote wake from a full power-off.

Is my data encrypted in transit?

Yes. All communication between devices, agents, and our servers uses TLS 1.2 or later. WebSocket connections are established over wss:// (WebSocket Secure).

How many devices can I add?

There is no hard limit during the current public launch period. Each device is listed separately in your dashboard.

What happens if the relay is unreachable?

Commands sent while a device is offline are queued (up to 10 pending commands per device) and delivered as soon as the device reconnects. The agent and firmware both implement exponential backoff reconnection.

Can multiple users access the same device?

Device sharing between accounts is not yet available. It is on the roadmap. Currently, you would need to share account credentials (not recommended) or wait for the sharing feature.

Does the Desktop Agent run as a service or as the logged-in user?

It runs as a Windows Service (SYSTEM account on Windows, root-owned systemd service on Linux). This allows it to remain connected even when no user is logged in, and to execute privileged commands like shutdown and restart.

Troubleshooting

Device shows as offline even though the agent is running

• Check that the agent service is running: sc query OnOffMyPCAgent (Windows) or systemctl status onoffmypc-agent (Linux).
• Confirm the machine has outbound access to port 443. Some corporate firewalls block WebSocket upgrades — try from a different network to confirm.
• Check agent logs for authentication errors — the pairing code may have been entered incorrectly. Re-pair by running onoffmypc-agent pair --code <new-code>.

ESP32 won't connect to WiFi after flashing

• Confirm you are on a 2.4 GHz network — the ESP8266 does not support 5 GHz and the ESP32 (non-S3) has limited 5 GHz support.
• Re-enter WiFi credentials via the captive portal. Hold the BOOT button for 5 seconds to reset WiFi settings and re-enter provisioning mode.
• Check that the SSID has no special characters or spaces (some older ESP8266 builds have issues with these).

Commands are queued but never delivered

• Make sure the device is actually online (green indicator in dashboard).
• If pending commands are accumulating, the queue caps at 10 — cancel older commands if needed.
• For hardware devices, ensure the GPIO wiring is correct and the board is powered.

Browser flasher says "No serial port found"

• Use Chrome or Edge — Firefox does not support the Web Serial API.
• On Linux, add yourself to the dialout group: sudo usermod -aG dialout $USER, then log out and back in.
• Try a different USB cable. Some cables are charge-only and do not carry data.
• Install the CP2102 or CH340 USB driver if prompted (required on some Windows systems).

Telemetry values show "Unknown" in the dashboard

• For temperature/humidity, make sure a DHT11 or DHT22 sensor is connected to the correct GPIO pin and the firmware was configured with the correct pin number before flashing.
• For CPU temperature on the software agent, some virtual machines and older hardware do not expose temperature sensors to the OS.

Contact & support

If you have a question not covered here, please use the contact page. Include your device type (software agent or hardware board), your operating system, and any relevant log output.

For firmware bug reports or feature requests, open an issue on the GitHub organisation.

For security vulnerabilities, do not file a public issue — contact us privately via the details in SECURITY.md.