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 setFIELDHAND_TOKEN.
Something wrong or missing on this page? Tell us.