Documentation

SpadeIDE has two moving parts: the app on your iPad and an agent on each machine you want to reach — your workstation, a home server, a VPS. The agent owns the filesystem and the shell on that host; the app draws the interface and keeps your machines behind one switcher. Everything else in these docs is detail on top of that.

Quick start

1 · Install the agent

On each machine you want to reach — Linux desktop, headless server, or a Mac:

# macOS — open the .dmg and drag SpadeIDE Agent to Applications, then launch it.

# Ubuntu / Debian
sudo apt install ./spadeide-agent_1.0.0_amd64.deb
spadeide

Full instructions, including running it as a service at boot: macOS · Linux.

2 · Pair the iPad

Running spadeide with no arguments prints a QR code and a pairing URL. On macOS the same QR is in the menu-bar popover. In the app, tap Pair a host and scan it.

The QR carries the agent's certificate fingerprint, so the iPad pins the correct machine before it sends anything. The pairing code is single-use and expires after ten minutes.

On a Linux system install (shared host), the iPad then asks for a Unix username and password once — that binds the tablet to one account’s home. Ordinary user installs skip that step. Details: which install · on the iPad.

Pair a host — paste the pair URL or scan the QR

3 · Open a project

Tap Open Project and pick a folder. That folder becomes the write root and the working directory for new terminals. Your home directory stays browsable but read-only, so you can find the folder without exposing the whole disk to writes.

Concepts worth knowing

Project = write root

Opening a folder as a project is what grants write access to it. Anything outside your open projects can be listed and read, never written. This is accident-prevention — see the security model for what it is and is not.

Pairing is the security boundary

A paired iPad gets a login shell on your host. That is the point of the product, and it is also why pairing is guarded the way it is: a single-use code, a certificate fingerprint pinned from the QR, and a device key generated inside the iPad's Secure Enclave that cannot be extracted. Revoke a device from the tray or with spadeide unpair.

Your own network vs. anywhere else

On the same network the iPad finds the agent over Bonjour and connects directly — no internet traffic at all. Off your network, the agent has to be reachable, which means turning remote access on:

spadeide remote on          # register with the introducer
spadeide remote status      # check
spadeide remote off         # back to local-only (the default)

Remote access is off by default. While it is off, the agent never contacts anything on the internet.

Ports at a glance

Port	Who listens	Exposure
`7422/tcp`	Agent — TLS, for your iPads	Your LAN. Never forward it to the internet.
`7423/tcp`	Agent — control API	`127.0.0.1` only, token-gated.
`443/tcp`, `443/udp`	Rendezvous server	Only if you host your own introducer.

You never need to open an inbound port for remote access. The agent dials out. If you find yourself forwarding 7422, stop — that exposes your host directly and remote access exists precisely so you do not have to.

Where to go next

Installing and running the macOS agent — menu bar, login item, folder permissions
Which Linux install to use — desktop, one account, or shared host with Unix login
Linux agent reference — install, service, day-to-day commands, environment
What the iPad shows — pair → Unix login (system) → open a project
Reinstall without losing pairings
Hosting your own rendezvous — full server setup with all configuration keys
Security model — what is protected, what is not, and why
Troubleshooting — discovery, pairing, Unix login, drops