Remote console & local shell

Debug live devices from the NervesHub web UI: enable the remote IEx console and the local shell, and understand their differences.

Written By Josh Kalderimis

Last updated About 2 months ago

NervesHub can open an interactive session into a running device from the web UI, so you can debug and recover hardware without physical access. There are two options:

Remote IEx console

Local shell

What you get

An Elixir IEx session in your firmware's runtime

A system shell on the device

Enabled by

remote_iex: true in config

On by default in the client, plus server settings

Extra dependency

None

ExPTY

Good for

Inspecting app state, running Elixir

OS-level debugging, poking at the filesystem

Both require the right permissions on your NervesHub account.

Remote IEx console

The IEx console is off by default. Enable it in your target config:

config :nerves_hub_link, remote_iex: true

Then open the device's Console page in the web UI to get a live IEx prompt in your running firmware.

The console process starts on the first request and stops after 5 minutes of inactivity. Adjust the timeout (in seconds):

config :nerves_hub_link, remote_iex_timeout: 900

Sending and receiving files

Newer clients support transferring files over the console connection, which is handy for pulling a log off a device or pushing a small file during debugging. This needs a client with console support version 2.0.0 or later.

Local shell

The local shell exposes an interactive system shell (not IEx) in the web UI. It's useful for OS-level troubleshooting.

It's enabled in the client by default, but it needs two things:

  1. The ExPTY library in your device's dependencies:

    {:expty, "~> 0.5"}

  2. The extension enabled in your Product and Device settings on NervesHub.

Once both are in place, open the device's Local shell page in the web UI.

Permissions

Seeing a device and opening a console or shell both depend on your role in the organization. If the Console or Local shell option isn't available, check your account's permissions.

Related