Documentation

Your remote workstation, clearly documented.

This page explains how Blackhole works, how to set up Horizon and Voyager, and how to keep the system stable when you move between local and remote work.

Quickstart Core Concepts Sharing and Access Sessions and Groups Troubleshooting

Design Principles

  • 01 Workstation-centric. One workstation, wherever you are.
  • 02 Horizon runs on the host and stays online.
  • 03 Voyager is the remote entry when you are away.
  • 04 One workspace across screens. Keep going when you leave the desk.
  • 05 Sessions and groups keep terminals tidy.
  • 06 Remote access works without LAN port forwarding.
Quickstart
Bring a workstation online
Step 1

Install Horizon and Voyager

Download Horizon for the host workstation and Voyager for your laptop or phone. Keep Horizon online on the host.

Step 2

Connect over LAN

Best for local networks.

  • Horizon Enable Allow LAN Access in Sharing.
  • Copy the URL Access shown in Horizon.
  • Voyager Enable LAN mode and paste the URL to connect.
Step 3

Connect over Wormhole

Use this when you are off the LAN. No port forwarding required.

  • Horizon Enable Allow Remote Access in Sharing.
  • Set the Wormhole URL and Access Token (use the official Wormhole if not self-hosting).
  • Optional Set a Custom Session ID.
  • Verify Wormhole Status shows Online.
  • Voyager Disable LAN mode, enter the Session ID and Wormhole URL, then connect.
Concepts
How Blackhole thinks

This Device vs Remote

Blackhole keeps a single perspective in the UI. The header always reflects the device you are actively working on.

  • This Device Local sessions on the host where Horizon is running.
  • Remote Sessions routed through Voyager to another host.

Sessions and Capabilities

Sessions are your active terminals on a target machine. Capabilities enable sharing and remote access.

  • Session An active terminal running on a host.
  • Group An organizing layer for multiple sessions.
  • Sharing LAN or Wormhole access, controlled in Settings.
Sharing
Make a host reachable

LAN Access

Fastest path for local networks. Horizon advertises a direct WebSocket address.

  • Enable Allow LAN Access in Sharing.
  • Connect Use the LAN URL inside Voyager.

Wormhole Access

Use a relay when you are away from the LAN. Allow Remote Access enables Wormhole.

  • Configure Wormhole URL + Access Token.
  • Status Check Wormhole Status in Sharing.

Pairing and Trust

New devices request approval once. Trusted devices reconnect automatically.

  • Approve First-time pairing in Horizon.
  • Manage Trusted Devices list in Settings.
Sessions
Stay organized while multitasking

Terminal groups

Group sessions by project or machine. Rename sessions for quick scanning.

  • Add Use the plus icon next to a group.
  • Rename Double-click a session name.
  • Sync Voyager edits sync when the drawer closes.

Keyboard tools

Quick Actions and HHKB tools provide mobile-friendly shortcuts.

  • Keyboard Tools Toggle the bottom bar in Settings.
  • HHKB Enable the HHKB keyboard on mobile.
Troubleshooting
Common issues and fixes

Voyager connects but no input

Verify the session is active in the drawer. If on the same host, ensure Horizon is running.

Wormhole stays Offline

Confirm URL scheme is ws/wss and token matches the relay. Check firewall rules.

Session list out of sync

Close and reopen the Sessions drawer to flush pending changes.