Getting started

You'll need:

The ondevice client software is open source (hosted on GitHub) and written in Go.

We provide a package repository for debian based distributions and a one-line installer script to install the application.

We're still working on packaging for other systems (RPM packages, homebrew on macOS, ...). For the time being, the one-line installer will simply install the binary to /usr/local/bin/ondevice

Install ondevice:

Note: This section mostly focuses on Debian based systems right now. The installer script will work on others as well (has also been tested on CentOS and MacOS), but there's no equivalent for the ondevice-daemon package yet.
We're working on it, but it'll take a little more time (you can however copy ondevice-packaging's init.d script and set up autostart yourself)

To install the ondevice client software simply run:

curl -sSL|sudo bash

On debian-based systems this will set up the repository and install the ondevice package

On other systems it'll detect the OS and architecture and download the right binary (and save it to /usr/local/bin).

If that didn't work, visit the ondevice-packaging github page) and file an issue.

Device side:

To autostart ondevice daemon, install the ondevice-daemonpackage (using apt-get). It'll ask you for your device credentials (can be found on your account page) and set up autostart

$ sudo apt-get install ondevice-daemon

That should be it. After a few seconds, ondevice status should print the device's ID. You'll need this ID to connect to the device (you can change the ID on your account page)

Client side:

Now that you've set up the device, install ondevice on the client as well.

Set up your client credentials (for the demo account: demo and caxuaph5th):

ondevice login

That's it, you're good to go.

Further steps

The following client commands might come in handy:

ondevice help is your friend. It covers a lot more than this quick guide.
If you find inconsistencies though, let us know
$ ondevice help
- Device commands:
    daemon [--conf=ondevice.conf] [] [--sock=unix://ondevice.sock]
         Run the ondevice device daemon
         Stops the local ondevice daemon (if running)

- Client commands:
    device <devId> <props/set/rm> [...]
         List/manipulate device properties
    list [--json] [--props] [--status=<online/offline>]
         List your devices
    rsync [rsync args...]
         Copy files from/to your devices using rsync
    ssh [ssh-arguments...]
         Connect to your devices using the ssh protocol

- Other commands:
         Log in to the service
    help [cmd]
         Shows this help screen
    status [--json]
         Prints the client and local device status

As you can see in the above ondevice help output, there's the device and the client side.
On the device side, ondevice daemon is probably the most important command.
On the client side, ondevice ssh and ondevice rsync will probably be the commands you'll use the most.

There's also ondevice device <devId> <props/get/set> which lets you manage user defined device properties which make it easier to manage larger numbers of devices in scripts etc.

For help on autostarting ondevice daemon, have a look at the FAQ section below



Need more?

  • Good news for you:

    We haven't enabled full traffic accounting yet, so right now the aforementioned limits aren't enforced yet.

    But if you expect to exceed those limits, we'd appreciate it if you sent us a quick email.

  • Contact us


  • Want to use for your non-profit or educational project? Send us a short email with some details about you and your project and I'm sure we'll figure something out.
  • Contact us


For debian based systems, you can install the ondevice-daemon package (which will ask you for your device credentials)

On other systems, the only officially supported way to autostart ondevice is to create a crontab entry (provided you have cron installed).
Create the file /etc/cron.d/ondevice with the following contents:

# automatically start the 'ondevice' daemon on system boot

@reboot	<username>	/usr/local/bin/ondevice daemon

Make sure to place the crontab file in the specified path. Future implementations of ondevice setup might detect that and be able to replace it with a proper init script.

In theory you can tunnel pretty much anything through the network.
The idea behind the ondevice client is to ship with a bunch of different protocol modules (and/or a generic TCP tunnel). And it allows you to add your own.
Right now though the client's code structure isn't considered stable (plus there's no transparent end-to-end encryption or authentication), so I recommend using the SSH module for the time being.

Some examples:


ondevice ssh <user@devID> -L 5900:localhost:5900 -N

You can then simply connect to VNC on localhost:0. ssh will tunnel all your traffic to the VNC server (while being tunneled through the ondevice network itself)


ondevice ssh <user@devID> -L 1234:localhost:80 -N

After the connection's been established, you can browse to http://localhost:1234/

SSH Socks5 proxy

ondevice ssh <user@devID> -D 1080 -N

Then update your browser's proxy configuration to point to localhost:1080 and you're good to go.

Well, the client's written in Go but (currently) uses some locking mechanisms for ondevice daemon which are only implemented for UNIX based systems.

You'll also need a running SSH server.

But if you're willing to put in some time, feel free to fork the ondevice client repo and go bug hunting.

That really depends on your use case. One key advantage is that is firewall friendly (which is especially useful if you've deployed many devices in different environments).

Another (rare, but still relevant) issue is that VPN IPs might clash with the IP of the local network (which can cause either to fail and is a real pain to work around)

Also, instead of exposing the whole PC, ondevice only shares select services (the default is to only share SSH which in itself is relatively secure)

First of all, only you (and the people you explicitly give access) can access your devices.

All the ondevice client does is to allow access to other services (in the default installation only SSH), and to connect to those services clients have to authenticate (so as long as you only enable secure services like SSH, you should be safe even if your credentials were breached)

And: All the code that's being installed on the clients/devices is open source software.