Edge sites

Agents in sandboxes can configure and inspect field devices (PLCs, HMIs, gateways) at a plant. An edge relay runs at the site, for example on a Raspberry Pi or an industrial PC. It makes outbound HTTPS connections only. Nothing listens at the site and no VPN is needed.

A sandbox reaches a device as <target>.<site>.edge, for example hmi.plant-a.edge. The egress proxy carries the traffic and the audit log records every stream (kind edge).

Three keys

A target opens only when all three agree:

The relay lists it. The relay has an allowlist, EDGE_TARGETS, set at the site. Nothing outside it is reachable, whatever the cloud asks.
An organization admin approved it. The relay reports its targets. An admin approves each target in Settings, Edge sites. The approval is for the exact spec the relay reports. If someone changes the target at the edge (another address, read to full, a login added), the approval no longer matches and the target stays closed until an admin approves it again.
The agent has a grant. An agent or workspace reaches only the targets it was given (see below).

Revoking an approval, removing a grant, stopping the workspace, rotating the token or deleting the site closes open streams within 60 seconds.

Add a site and install the relay

Open Settings, Edge sites and select Add site. Give it a name and a slug. The slug is the middle part of the host name. It uses lowercase letters, digits and hyphens, up to 40 characters.
DELEGATE shows the relay token once. Copy it. If you lose it, rotate the token. The old token stops working at once.
On a device at the site that can reach the plant network, run the install command that the page shows:
Terminal window
```
curl -fsSL https://<api host>/api/v1/edge/relay/install.sh | sudo bash -s -- \
  --token <token> \
  --targets 'hmi http read https://192.168.10.5 insecure; plc1 modbus read 192.168.10.20:502'
```
The script installs the relay as a hardened systemd service. Run it again with new --targets or --credentials to change them. Other options: --upgrade, --status, --uninstall.
When the relay connects, the site shows as connected and its targets appear with the state Not approved.

Deployment with logiccloud orchestrate comes later.

Targets

One target per line, or separated by ;:

<name> <kind> <mode> <address> [option ...]

hmi    http   read  https://192.168.10.5   insecure  auth=HMI_LOGIN
plc1   modbus read  192.168.10.20:502
gw     tcp    full  192.168.10.30:22

Field	Values
name	Lowercase letters, digits and hyphens, unique at the site. It becomes `<name>.<site>.edge`.
kind	`http`, `modbus` or `tcp`.
mode	`read` or `full`. `tcp` takes only `full`.
address	`http`: `http(s)://host[:port]` without a path. `modbus` and `tcp`: `host:port`.
options	`insecure`, `auth=NAME`, `max=N`.

Modes

read: the relay lets only reads through. For http: GET, HEAD and OPTIONS without a body. Other methods, method override headers and WebSocket upgrades get a 403 at the relay. For modbus: function codes 1 to 4 (read coils, inputs and registers) and device identification. A write gets Modbus exception 01 at the relay and never reaches the device.
full: everything passes, including writes. DELEGATE asks you to confirm before you approve a full target.

read limits what the relay lets through. It cannot know what a device does on a GET. A web UI that switches an output on GET /set?q1=1 does so in read mode too. Approve read only for devices whose UI does not act on a GET.

Options

insecure (http only): do not verify the certificate of an HTTPS device. Many devices have a self-signed certificate.
auth=NAME (http only): the relay sends HTTP Basic credentials to the device. NAME names a login that you give the relay in EDGE_CREDENTIALS (or --credentials of the install script), as NAME=user:password, one per line or separated by ;. The logins stay on the edge device. DELEGATE and the sandbox never see them.
max=N: at most N streams to this target at once, 1 to 64.

Approvals

In Settings, Edge sites each target shows one state:

State	Meaning
Approved	The relay reports the approved spec. The target can be used.
Not approved	The relay reports it, nobody approved it yet.
Changed at the edge	The relay reports another spec. The page shows both. Approve again.
Approved, not reported	The relay does not offer the target now.

Only organization admins add sites, rotate tokens, delete sites and approve or revoke targets. Other people with access see the page read-only.

Grants

In the access section of an agent version or a workspace, Edge targets lists the sites. Tick a site and choose All approved targets or Specific targets. With all targets, a target approved later is included. A grant never opens a target that nobody approved.

What the agent uses

A workspace with edge grants starts with:

the edge command in the sandbox: edge list shows the granted targets, edge get <name> [/path] reads an http target, edge modbus <name> id, scan, read-ir, read-hr, read-coils and read-di read a modbus target, and edge tcp <name> opens a raw stream for other tools. It handles the egress proxy; the agent never sees a device’s address.
the edge skill: how to explore a device read-only, where scalings and addresses come from, and that writes belong to the runtime’s program, not to the relay.

To try it without a plant, run the EMS remote I/O simulator (apps/edge-relay/simulator) next to the relay on a Raspberry Pi.

Limits

A PLC has only a few Modbus connection slots, often shared with the plant’s SCADA. The system caps streams to protect them:

Per target at the relay: max=N. The default is 4 for modbus and tcp, and 8 for http.
Across all targets at the relay: EDGE_MAX_STREAMS, default 64.
At the hub: 16 streams per sandbox and 64 per site, and a limit on how fast streams open.
Idle streams close after 5 minutes without traffic (EDGE_STREAM_IDLE).

A stream over a limit is refused with the reason, and the sandbox can read it.