HORUSdocs
homesource ↗
Docs menu
horus CLI

Overview and install

Use your phone from a computer, like a small cloud VM.

horus is a small command-line tool for your computer. It lets you use a phone running Horus the way people use a cloud VM: open a terminal on it, copy files, run a web server on it and view it on your laptop. You can do all of that with several phones at once.

Everything goes over the USB cable. Nothing on the phone is reachable over Wi-Fi.

You want to…Run
See which phones are plugged inhorus devices
Open a terminal on the phonehorus ssh
Copy files to or from the phonehorus cp
Open a phone's web server on your laptophorus forward 3000
Run a command on every phonehorus exec --all -- …
Use the phone in VS Codehorus config --install

What you need

  • A Mac or Linux computer.
  • A USB cable that carries data. Some cheap cables only charge. If your computer doesn't notice the phone, try another cable.
  • Horus installed and set up on the phone (you've created your password).
  • Three free tools on the computer: Node.js, adb and OpenSSH. The steps below cover each one.

Set up your computer

Open the Terminal app on your computer (on a Mac: press ⌘ Space and type "Terminal"). Type or paste each command and press Return.

  1. Install Node.js (version 18 or newer)

    Download it from nodejs.org (the LTS version), or with Homebrew on a Mac. Then check it worked:

    your computer
    node --version
    you'll see something like
    v22.11.0

    Any number from 18 up is fine.

  2. Install adb

    adb is Google's tool for talking to Android phones over USB. It comes in a package called platform-tools.

    macOS (with Homebrew)
    brew install android-platform-tools
    Ubuntu or Debian
    sudo apt install adb
    Fedora
    sudo dnf install android-tools
    Arch
    sudo pacman -S android-tools

    Or download platform-tools directly from Android's website. If adb isn't on your PATH, tell horus where it is with ADB=/path/to/adb.

  3. Check OpenSSH

    macOS and most Linux systems already have ssh and scp. For horus sync you also need rsync, which is on macOS already and is one package install on Linux.

    your computer
    ssh -V

  4. Install horus

    your computer
    npm install -g horus-cli

    Check it's there:

    your computer
    horus help
    you'll see something like
    horus — use Android phones running Horus like small Linux machines, over USB.

Usage:
  horus devices                       List connected phones and their state
  horus pair [phone] [--name NAME]    Trust this computer (asks for the Horus password)
  horus ssh [phone] [-- command...]   Open a shell, or run one command
  …

    If you get a "permission denied" error on Linux, your npm is set up to need admin rights for global installs. Use a Node version manager like nvm, or put sudo in front of the command.

Set up the phone

The CLI talks to the phone through USB debugging, a switch hidden in Android's developer options. Turning it on is safe, and you can turn it off again any time.

  1. Unlock developer options

    Open Settings → About phone and tap Build number seven times. (On some phones it's under Software information.) You'll see "You are now a developer".

  2. Turn on USB debugging

    Go to Settings → System → Developer options (on some phones, just Settings → Developer options) and switch on USB debugging.

  3. Plug in and allow your computer

    Connect the phone with the cable. The phone asks "Allow USB debugging?" Tick Always allow from this computer and tap Allow.

    your computer
    horus devices
    you'll see something like
    NAME  SERIAL          MODEL    BATTERY  STATUS
-     1A2B3C4D5E6F7G  Pixel 8  84%+     not paired (run `horus pair`)

    Your phone is listed, and + means it's charging. Now pair it.

Update or remove

your computer
# update to the latest version
npm update -g horus-cli
# remove it (your keys and pairings stay in ~/.horus)
npm uninstall -g horus-cli