Remote hardware bridge

embedder-bridge is a service for hardware attached to another machine. The agent stays on your workstation while serial data, flash commands, managed debug processes, and file transfers cross an authenticated connection.

Choose a deployment

Deployment	Command	Network path
Temporary LAN bridge	`embedder bridge start`	Listens on `0.0.0.0:4849` and advertises over mDNS
Relay-enrolled temporary bridge	`embedder bridge start --relay`	LAN listener plus outbound relay registration when the config is first created
Linux or macOS service	`sudo embedder bridge install-service`	A new config uses a loopback listener plus outbound relay registration
Manual binary	`embedder-bridge --config <path> run`	Uses the TOML file exactly

The CLI carries a platform-specific bridge binary and extracts it below the Embedder application directory. install-service copies that binary to /usr/local/bin/embedder-bridge.

Start a temporary LAN bridge

On the machine with the hardware:

embedder bridge start

The command writes its first config to ~/.embedder/bridge/config.toml, stores state under ~/.embedder/bridge/state, and starts a detached process.

Bridge running on 0.0.0.0:4849 (pid 23104).

From your workstation:

embedder bridge discover

Discovery browses _embedder-bridge._tcp.local. The bridge advertises its configured name, port, protocol version, fingerprint, and pairing state. If multicast DNS is unavailable, use the address directly in later commands.

Pair over the LAN

Open a pairing window on the bridge host

embedder-bridge --config ~/.embedder/bridge/config.toml pair

The command prints a Crockford Base32 code. It is valid for two minutes, is single use, and allows five attempts.

Redeem the code from the workstation

embedder bridge pair 192.0.2.25:4849 \
  --name bench \
  --code 8N4K2W7Q

You may replace the direct address with an exact mDNS instance name:

embedder bridge pair embedder-lab-pi --code 8N4K2W7Q

Verify the fingerprint

The workstation prints the fingerprint returned during pairing. Compare it with embedder-bridge status on the bridge host before accepting it as trusted.

Test the saved pairing

embedder bridge status
embedder bridge doctor bench

doctor checks the pinned connection, serial enumeration, common flash and debug binaries, and a file-transfer round trip.

The workstation stores the bridge address, fingerprint, client ID, and issued token in ~/.embedder/bridges.json. The file is set to mode 0600 where supported. The bridge stores a hash of the client token, not the token itself.

Install a relay service

Run this on the bridge host:

sudo embedder bridge install-service

The installer:

Copies the bundled binary to /usr/local/bin.
Preserves an existing config or creates one.
Creates the state directory.
Installs and starts a service.
Configures the production relay.

The generated config binds to 127.0.0.1:4849. Remote clients reach it through the relay rather than an inbound LAN port.

Linux service

Linux uses:

/etc/embedder-bridge/config.toml
/var/lib/embedder-bridge
/etc/systemd/system/embedder-bridge.service

The installer creates a system user named embedder-bridge, adds it to dialout and plugdev, sets the state directory to mode 0700, and enables the systemd service.

journalctl -u embedder-bridge -f

macOS service

macOS uses:

/usr/local/etc/embedder-bridge/config.toml
/usr/local/var/embedder-bridge
/Library/LaunchDaemons/dev.embedder.bridge.plist
/usr/local/var/log/embedder-bridge.log

The launch daemon starts at boot and keeps the process alive.

Override install paths

sudo embedder bridge install-service \
  --bin-dir /opt/embedder/bin \
  --state-dir /srv/embedder-bridge

The config directory and service file location stay platform-defined.

Claim the relay enrollment

On first service start, the bridge registers with the Embedder relay and returns a setup code. Open the Bridges page in the Embedder app, add a bridge, and enter that code. After the claim, client traffic still runs inside the bridge’s pinned TLS session. The relay carries bytes but does not replace fingerprint verification.

A non-loopback ws:// relay URL is rejected. Use wss:// outside localhost, even though the inner bridge session is also encrypted.

Run this on the bridge host to ask the relay to remove the registration:

embedder-bridge --config /etc/embedder-bridge/config.toml deregister

Bridge configuration

The binary reads TOML and rejects unknown fields.

/etc/embedder-bridge/config.toml

name = "lab-bench"
bind = "127.0.0.1"
port = 4849
state_dir = "/var/lib/embedder-bridge"
exec_allowlist = []
relay_url = "wss://relay-service-prod.embedder.com"
instruments_enabled = true
probe_interrogation_enabled = true

Field	Default	Behavior
`name`	`$HOSTNAME` or `embedder-bridge`	mDNS and status name
`bind`	`127.0.0.1`	TCP listener address
`port`	`4849`	TCP listener port
`state_dir`	`/var/lib/embedder-bridge`	Identity, clients, staging, audit, and relay files
`exec_allowlist`	`[]`	Allowed executable names; empty permits any program
`relay_url`	unset	Enables relay setup or registration
`instruments_enabled`	`false`	Advertises the scripts capability
`hardware_descriptor`	unset	Optional board and target descriptor
`probe_interrogation_enabled`	`false`	Enables active probe inventory

Changing bind away from loopback enables mDNS advertisement. Every session still requires pairing or relay authentication.

Manage the bridge from the CLI

On the bridge host, embedder-bridge can run the service, show status and diagnostics, open pairing, manage clients, remove relay enrollment, or reset its identity. On the workstation, embedder bridge can discover, pair, list, remove, test, and execute against saved bridges. See the CLI reference for the complete command syntax and options.

embedder-bridge reset-identity changes the fingerprint and revokes every client. Re-pair all workstations after running it.

bridge exec defaults to a 10-minute timeout. The command runs in the bridge staging directory. A requested working directory must remain inside staging. When exec_allowlist is nonempty:

The first argument must appear in the list.
Shell mode is disabled.

Every execution writes an audit record with the client ID, command, exit code, and timeout state. Uploads are limited to 512 MiB, downloads to 64 MiB, and remote execution to 30 minutes.

Security model

TLS uses a stable bridge key and client-side fingerprint pinning.
Pairing codes expire after two minutes.
Client tokens are stored hashed on the bridge.
Repeated authentication failures lock out further attempts, up to one hour.
LAN and relay sessions use the same authenticated bridge protocol.
File working directories are confined to staging.

Pairing authorizes remote command execution by design. Use a dedicated operating-system account, an exec_allowlist, and device permissions that match the intended lab access.

Troubleshooting

Discovery finds nothing

mDNS only runs when the bridge binds outside loopback. Check bind, UDP multicast between the hosts, and the _embedder-bridge._tcp.local service. Pair directly with host:port when multicast is blocked.

The bridge identity changed

The pinned fingerprint differs from the current bridge. Confirm whether the state directory or identity was reset. Remove and re-pair only after verifying the new fingerprint on the bridge host.

Serial ports are missing

On Linux, confirm that the service user belongs to dialout and that USB probe udev rules grant plugdev access. embedder-bridge diagnose prints the hardware inventory visible to the service.

A flash command is rejected

Check exec_allowlist. An empty list permits programs; a nonempty list must contain the exact first argument. Shell execution is unavailable while that list is active.

Relay enrollment never completes

Read the service log for the setup code, confirm outbound WSS access to the relay, and claim the current code in the Embedder app. Expired setup codes are replaced automatically.

Doctor reports no flasher or GDB server

Install probe-rs and either OpenOCD or J-Link GDB Server on the bridge host. The service process must be able to find them on its PATH.

CLI reference

Check every bridge command and option.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

API

Remote hardware bridge

Choose a deployment

Start a temporary LAN bridge

Pair over the LAN

Install a relay service

Linux service

macOS service

Override install paths

Claim the relay enrollment

Bridge configuration

Manage the bridge from the CLI

Security model

Troubleshooting

CLI reference

​Choose a deployment

​Start a temporary LAN bridge

​Pair over the LAN

​Install a relay service

​Linux service

​macOS service

​Override install paths

​Claim the relay enrollment

​Bridge configuration

​Manage the bridge from the CLI

​Security model

​Troubleshooting

CLI reference

Choose a deployment

Start a temporary LAN bridge

Pair over the LAN

Install a relay service

Linux service

macOS service

Override install paths

Claim the relay enrollment

Bridge configuration

Manage the bridge from the CLI

Security model

Troubleshooting