Guide

wisq does two separate things, and which one you want decides everything that follows. Reaching a virtual machine that runs on a Mac, a PC or a NAS gives you a full desktop at the speed of that machine. Booting Linux on the phone itself gives you a shell with no network at all. Neither needs a jailbreak.

Remote: a VM on your own hardware

wisq speaks two console protocols. RFB 3.8 — VNC — reaches anything that exposes a VNC console: QEMU, libvirt, VirtualBox, Proxmox, a Raspberry Pi running x11vnc, a Mac sharing its screen. SPICE reaches what libvirt hosts usually publish instead, and carries more: sound both ways, the clipboard, and its own image codecs.

qemu-system-x86_64 -m 2048 -vnc :1 -hda disk.qcow2

# or expose a display that already exists
x11vnc -display :0 -rfbport 5901

1. In wisq, tap + and give the machine a name.
2. Enter the host and port. A VNC display of :1 means port 5901 — the port is 5900 plus the display number.
3. Enter the password if the server asks for one; it is stored in the iPhone Keychain, never in the machine list.
4. Tap the machine to connect.

The agent: turning a VM on before connecting

Without the agent wisq still works, as long as the VM is already running. The agent is what turns "one more VNC client" into "my machines, from my phone": tapping a powered-off VM boots it, waits for its console and connects to whatever port it landed on.

Run it with --service and it installs a launchd job on macOS or a systemd user unit on Linux, so it survives a reboot. Run it with --demo first if you want to see the phone side working before pointing it at a hypervisor: it serves two fake VMs with real state transitions.

On first start the daemon prints a pairing link per reachable address, and a QR code when qrencode is installed. Open one on the iPhone — scan it, or paste it — and wisq lands on the import screen with the address and token already filled in.

wisq-agent en écoute sur le port 7442 (virsh)
jeton : k3f9x2m8q1w7e4r6t5y0u8i2o4p6a1s3
appairage :
  wisq://agent?host=nas&port=7442&token=…&name=nas

The token is generated once and kept in ~/.wisq-agent/token with owner-only permissions. Revoking access is deleting that file and restarting the daemon.

Local: Linux on the phone itself

The local machine is an interpreted RISC-V computer — one rv32ima hart, 64 MB of RAM, an 8250 UART, a CLINT timer. It boots a real Linux kernel to a login prompt in a fraction of a second, with no network and no host.

1. Get an rv32ima nommu kernel image. Ready-made ones live in the mini-rv32ima project.
2. Put it somewhere the Files app can reach — iCloud Drive, or On My iPhone.
3. In wisq, open the local machine screen and import the image.
4. Tap boot. The console appears as the kernel writes to its UART.

The virtual clock advances with executed instructions rather than wall time, so the same image boots the same way on every device — which is also what makes the boot testable in CI.

When something does not work

The screen stays black after connecting

The server accepted the connection but is not sending updates. Check that the VNC server is attached to a display that exists — a headless QEMU with no -vga will connect and show nothing.

Colours look wrong

Report it. wisq negotiates a pixel format for rendering rather than accepting the server's, and a mismatch is a bug on our side, not a setting on yours.

The agent says a domain is unknown

The daemon asks libvirt through virsh, so it sees exactly what `virsh list --all` sees — and as the user the daemon runs as. A VM defined for root is invisible to a daemon running as you.

The pairing link does nothing

The link only opens wisq if the app is installed. On a fresh phone, install first, then scan.

The local kernel boots and then stops printing

That is usually the login prompt, which ends without a newline. Type into it — the console is two-way.