Using Fieldhand

CLI: ssh and port forwarding

ssh, scp, rsync, VS Code Remote and any TCP port on a device, from your own terminal.

fh connects your computer to a port on a device through Fieldhand: the device's ssh server, a database, a PLC on its network. It works behind CGNAT and firewalls like the browser terminal does, and the device opens no inbound port.

Install

macOS and Linux (Intel or ARM):

curl -fsSL https://api.fieldhand.dev/dl/fh-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') -o fh
chmod +x fh && sudo mv fh /usr/local/bin/

Windows: download fh-windows-amd64.exe, rename it fh.exe and put it on your PATH. It uses the OpenSSH client that ships with Windows 10 and 11.

Then create an API token in Settings → API tokens (role member or admin) and paste it into fh login. See API for roles and tag scopes; a token scoped to some tags reaches only those devices.

fh login
fh devices

ssh into a device

This needs an ssh server on the device (OpenSSH or Dropbear, listening on port 22) and a user you can log in as. Without one, use the browser terminal.

fh ssh pi@kiosk-14
fh ssh pi@kiosk-14 'journalctl -u myapp -n 50'

For scp, rsync, Ansible and VS Code Remote-SSH, add the block that fh ssh-config prints to ~/.ssh/config. Every device is then reachable as NAME.fieldhand:

fh ssh-config >> ~/.ssh/config
scp firmware.bin pi@kiosk-14.fieldhand:/tmp/
rsync -av ./app/ pi@kiosk-14.fieldhand:/opt/app/

In VS Code, run Remote-SSH: Connect to Host and type pi@kiosk-14.fieldhand.

Forward a port

fh forward DEVICE [LOCAL:][HOST:]PORT listens on your computer and carries each connection to the device. HOST defaults to the device itself; a private address reaches equipment on the device's network.

fh forward kiosk-14 5432              # psql -h 127.0.0.1 → the device's Postgres
fh forward gw-portland 8502:192.168.1.50:502   # Modbus on a PLC behind the gateway

Device names

Use the name shown in the dashboard, the device id, or the first characters of the id. If two devices share a name, fh lists both and asks for the id.

Security

  • Each connection asks the API for a single-use ticket valid for 30 seconds, so a revoked token or a removed teammate can't open new connections. Viewers can't connect.
  • The device connects only to itself and to private network addresses, never to the internet.
  • Each connection is in the device's activity log and in the audit export.
  • The ssh session is end-to-end encrypted between your computer and the device's ssh server; Fieldhand carries the bytes and can't read them.

Limits

  • The free plan limits the speed to 512 KB/s per connection; paid workspaces get 4 MB/s.
  • The token is stored in ~/.config/fieldhand/cli.json (macOS: ~/Library/Application Support/fieldhand/cli.json), readable only by you. Or set FIELDHAND_TOKEN.

Something wrong or missing on this page? Tell us.