File transfer and direct LAN connections

The Agent, Exchange, CLI, web console and mobile console support file transfers. Supported devices advertise the files capability.

File transfer

remote-cli file i5m ls /tmp
remote-cli file i5m upload ./example.zip /tmp/example.zip
remote-cli file i5m download /tmp/example.zip ./downloaded.zip
remote-cli file i5m fetch https://example.com/example.zip ./example.zip

Existing files are not overwritten by default; add --overwrite when uploading or downloading to allow replacement. Cancel with Ctrl+C in the CLI or the cancel button in web/mobile consoles. Use the device detail Files tab on the web, or File transfer from device details on mobile.

Transfers use 64 KiB chunks, waiting for acknowledgment after each chunk. A single file is limited to 1 GiB; browser downloads are limited to 128 MiB, so use the CLI or mobile console for larger files. Directory listings return at most 1000 entries; recursive directory uploads are unsupported. Uploads write a temporary file in the destination directory and atomically replace the destination after receiving the full file. Cancellation, disconnection, and timeout clean up incomplete temporary files. CLI downloads also use temporary files; mobile downloads go to the cache and then invoke system sharing/saving.

File access uses the Agent process's operating-system permissions and is not restricted to a shared directory. Readonly accounts cannot list directories, upload, or download. Exchange retains workspace ownership checks, session isolation, and operation auditing without recording file contents. On Android, . points to the Agent app's files directory; other directories remain subject to Android permissions and the system sandbox.

Internet downloads through the Agent

Enter an HTTP/HTTPS URL in the web Files tab, or run file DEVICE fetch URL LOCAL. The Agent downloads from its own network and streams the file to the Console computer without saving it on the Agent. Web downloads are limited to 128 MiB; CLI downloads to 1 GiB. Cancellation, disconnects and failures discard incomplete files; existing CLI destinations require --overwrite. Native Agents (desktop, Linux, Android and OpenWrt) support this; the browser extension has no file transfer. Certificate verification remains enabled; URLs with embedded credentials and HTTPS downgrades are rejected, with at most five redirects.

The download does not inherit management-server --insecure.

Curl-style HTTP requests

Paste a curl command in the device HTTP request tab. The Console sends a sealed request to the selected Agent and displays status, elapsed time, headers and body. It parses -X/--request, -H/--header, -d/--data, --data-raw, inline --data-binary, --json, -I/--head, -L/--location, -m/--max-time and --url as data; it never executes shell expressions or reads @file. Native Agents use the shared HTTP engine without requiring curl. The browser extension needs site access permission, omits browser cookies, rejects forbidden headers and reports redirects hidden by Chromium; use the final URL. Readonly grants cannot send requests. Request bodies are limited to 256 KiB and timeouts to 120 seconds; responses are truncated at 1 MiB on native Agents or 128 KiB in the extension. Use file fetch for binary or larger downloads.

The sealed message is net_req. Browser capability: net. CLI equivalent: remote-cli net DEVICE http URL -X POST -H 'Content-Type: application/json' -d '{"message":"hello"}'

curl -X POST 'https://example.com/api' -H 'Content-Type: application/json' --data-raw '{"message":"hello"}'

LAN control port

LAN control is disabled by default, with default TCP port 7277. Enable it only on a trusted LAN. Before enabling, the device must have pinned its workspace root (remote-agent seal root, or connect to Exchange first to complete TOFU). There is no LAN access token. Do not forward the port to the public Internet.

Add these fields to the existing Agent JSON configuration:

{
  "lan_enabled": true,
  "lan_port": 7277
}

Keep the existing server, device_id, and token fields. Alternatively use --lan-enabled, --lan-port, or REMOTE_LAN_ENABLED, REMOTE_LAN_PORT. Enabling LAN without a pinned workspace root causes startup to fail.

Both desktop configuration and LuCI settings provide a switch. Restart the Agent after changing it; desktop configuration requires stopping the connection before editing. Turning the switch off and restarting stops listening on this port. The program does not automatically add firewall rules.

For CLI direct connections, write a separate configuration rather than using login (which requires a nonempty token). Set server to the device's http://IP:7277 and leave token empty; requests carry no Authorization header:

server = "http://192.168.1.20:7277"
token = ""

Point REMOTE_CLI_CONFIG to this file to retain a separate cloud login. Sealed identity and grant caches live beside this configuration: offline grants in seal-grants.json, and root-first certificate chains in seal-chains.json. All device operations open only sealed sessions, including direct connections whose device card has local or whose LAN /api/auth/me endpoint returns 401. The Agent neither issues nor renews these grants. While the cloud is offline, only still-valid root-chain grants in the cache are usable. sessions and session-kill are unavailable: LAN has no session directory, and Exchange continues to manage device sessions.

Direct connections expose only the local device. The outer layer accepts only private, link-local, or loopback addresses and validates Origin. After these checks, GET /api/devices returns only the device ID and seal_key / seal_mode needed to start the sealed handshake. GET /api/auth/me does not return operator identity before the sealed handshake. GET /ws/operator accepts only sealed sessions and provides no plaintext compatibility path.

The client includes operator public-key proof, the cached offline grant (hello.grant), and an optional root-first certificate chain (hello.chain) inline in the open_sealed hello. The device applies the same rules as the Exchange path to validate its local root, device scope, and view/manage permissions, keeping session contents sealed. The web console continues to connect through Exchange. By default, the listener binds all IPv4 interfaces and remains usable while the cloud is offline. A LAN bind failure is logged while cloud reconnection continues.

Regression validation

python scripts/file-transfer-smoke.py --agent target/debug/remote-agent --cli target/debug/remote-cli
python scripts/agent-ui-smoke.py --agent target/debug/remote-agent --platform linux

Requires Python 3.11+ and websockets. On Windows use .exe paths and --platform windows. Tests use temporary configurations and files without changing existing logins or devices.