HORUSdocs
homesource ↗
Docs menu
horus CLI

Pair a phone

Connect over USB and trust your computer.

Pairing tells the phone to trust your computer. You do it once per computer and phone. It uses your Horus password, so only someone who knows it can pair.

Pair your phone

  1. Open Horus on the phone

    Make sure setup is finished and the phone is unlocked and plugged in. horus devices should list it.

  2. Run horus pair

    your computer
    horus pair

    horus names the phone after its model and asks for the Horus password you set on the phone:

    you'll see something like
    Pairing Pixel 8 (1A2B3C4D5E6F7G) as "pixel-8".
Horus password on the phone:

    Type it and press Return. The password doesn't show as you type; that's normal.

  3. Wait for the first-time setup

    The first time, the phone installs its SSH server inside Horus. This takes a minute or so and needs internet on the phone. If Android won't start it in the background, horus opens the Horus app on the phone for you.

    you'll see something like
    Paired. The phone now trusts this computer's key SHA256:9fQ…
Tip: Android may kill busy background processes. Run `horus tune` once to lift that limit.
Ready. Open a shell with: horus ssh pixel-8

  4. Open a shell on the phone

    your computer
    horus ssh

    You're now in zsh on the phone; the prompt changes to show it. Try ls /workspace/projects to see your projects. Type exit to come back to your computer.

Choose your own name

Names are how you refer to phones in commands, like horus ssh pixel. Pick one when pairing:

your computer
horus pair --name pixel

Names use lowercase letters, digits and dashes, up to 32 characters, and each must be unique. If several phones are plugged in, give the serial from horus devices too:

your computer
horus pair 1A2B3C4D5E6F7G --name work-phone

When only one phone is connected, you can leave the name out of every command. The adb serial also works anywhere a name does.

What pairing actually does

  1. Creates an SSH key for this computer in ~/.horus (only the first time).
  2. Sends the public half of the key to the Horus app over USB, together with your password. The app checks the password and only accepts the request from a USB connection.
  3. Turns on remote access on the phone and starts its SSH server. The server only listens inside the phone, never on Wi-Fi.
  4. Remembers the phone's own key in ~/.horus/known_hosts, so later connections can check they reach the same phone.

Unpair or turn off

your computer
# remove this computer's key from the phone
horus unpair
# keep the pairing, but switch remote access off for now
horus stop

On the phone, SETTINGS → Remote access lists paired computers. REVOKE removes one, and the switch turns remote access off. The Remote access is on notification has a Turn off button too. To turn it back on, use Settings or run horus pair again.