LiveAgent Gateway
Drive a LiveAgent instance remotely over its gateway — from any agent, shell, or program.
The gateway is a relay, not an execution environment. It never runs shell commands, never touches a filesystem, and never stores credentials. It authenticates the caller, applies a whitelist, forwards the request to a desktop agent, and relays the answer back. Every privileged action happens on the desktop machine.
1. Required parameters
Collect these three before anything else. If the caller did not supply them, ask rather than guess.
| Parameter |
Env var |
Meaning |
How to obtain |
| Gateway URL |
LAG_GW |
Base URL, with scheme |
Deployment output, e.g. http://localhost:3000, https://gw.example.com |
| Token |
LAG_TOKEN |
Gateway token or agt_… per-agent token |
LIVEAGENT_GATEWAY_TOKEN at deploy time, or issued via the admin API |
| Agent ID |
LAG_AGENT |
Which desktop to target |
scripts/lag.sh agents, or desktop Settings → Remote → Agent ID |
Port conventions: direct container access uses the mapped host port (commonly 3000); behind a reverse proxy use the HTTPS URL and port 443.
If LAG_AGENT is unknown, run the agents command first — every targeted request needs a non-empty agent id.
2. Which transport to use
Decide by what the task needs. Most failures come from choosing the wrong one.
| Need |
Transport |
Reference |
| Health, agent status, credential administration, file upload, public share |
HTTP (curl / PowerShell) |
references/http-api.md |
| Chat, live events, agent switching |
WebSocket v2 |
references/chat.md |
| Filesystem, git, terminal, SFTP, tunnels, memory, cron, skills, settings, history |
WebSocket v2 pass-through |
references/remote-operations.md |
HTTP cannot send chat or reach a desktop. WebSocket cannot administer credentials. Use both.
3. Quick start
export LAG_GW="http://localhost:3000"
export LAG_TOKEN="<gateway token>"
export LAG_AGENT="agent-<uuid>"
# HTTP: health, status, directory
bash scripts/lag.sh health
bash scripts/lag.sh status
bash scripts/lag.sh agents
# WebSocket: handshake, chat, pass-through
python3 scripts/lag_ws.py probe
python3 scripts/lag_ws.py send "list the files in the workspace"
python3 scripts/lag_ws.py req HistoryList --json '{"1":1,"2":20}'
$env:LAG_GW="http://localhost:3000"; $env:LAG_TOKEN="<gateway token>"
.\scripts\lag.ps1 health
.\scripts\lag.ps1 agents
.\scripts\lag.ps1 issue-token -Agent "agent-<uuid>" -Name "office-pc"
Both CLIs read LAG_GW / LAG_TOKEN / LAG_AGENT, or accept explicit flags. lag.sh uses only curl; lag_ws.py uses only the Python 3 standard library.
4. Roles and credentials
Two connection roles exist, and they are not interchangeable:
| Role |
Endpoint |
Purpose |
BROWSER |
/ws/v2 |
The controller — you |
AGENT |
/ws/v2/agent |
The desktop being controlled |
| Credential |
Browser link |
Agent link |
Admin REST |
| Gateway token |
yes |
yes |
yes |
agt_… per-agent token |
no |
only its bound agent |
no |
- A leaked
agt_ token can impersonate one machine — never the browser, never the admin API, never other agents.
agt_ plaintext is shown once at issue time; only a SHA-256 hash is stored.
- Rotating a credential immediately disconnects that agent. Warn the operator before rotating.
- Prefer per-agent tokens over sharing the gateway token across machines.
5. Workflow
- Confirm
LAG_GW, LAG_TOKEN, and (for desktop work) LAG_AGENT.
- Verify reachability and auth:
lag.sh health, then lag.sh status.
- If the agent id is unknown, run
lag.sh agents and pick the intended machine.
- Select the transport from section 2 and open the matching reference.
- Execute the smallest request that answers the question; widen only if needed.
- Report the raw result. Never claim an action succeeded unless a response confirmed it.
6. Guardrails
- Never print or log the token. Pass it by environment variable or an env file with
600 permissions. Avoid command lines where ps can read it.
agt_ tokens are bound to one agent. They cannot reach another machine.
- Confirm before destructive or mutating calls —
FsDelete, FsRename, FsWriteText, credential rotation/deletion, MemoryManage, CronManage, SkillManage.
- Never target a host you do not administer.
- Do not treat an empty result as a safe result. Zero agents or an empty event window means no data returned, which is not the same as nothing is wrong. Confirm
online=true first.
- Respect the relay boundary. If a task needs a tool the gateway does not whitelist, say so instead of improvising.
- Report failures verbatim.
401, close code 4401, and local_error mean different things; see references/limits-and-errors.md.
7. References
references/http-api.md — HTTP endpoints, auth header, admin API, uploads, public shares.
references/protocol-v2.md — handshake, frames, message fields, envelope arm numbers.
references/chat.md — chat submit/edit/cancel, streaming, resume, idempotency, watchdogs.
references/remote-operations.md — filesystem, git, terminal, SFTP, tunnels, memory, cron, skills, settings, history.
references/limits-and-errors.md — size caps, concurrency, close codes, failure modes, recovery.
references/deployment.md — deploying, upgrading, reverse-proxying, hardening a gateway.
8. Scripts
| File |
Language |
Purpose |
scripts/lag.sh |
bash / zsh |
HTTP operations via curl |
scripts/lag.ps1 |
Windows PowerShell |
HTTP operations via Invoke-RestMethod |
scripts/lag_ws.py |
Python 3 (stdlib only) |
WebSocket v2: handshake, status, agents, chat, pass-through |
scripts/envelope_arms.json |
data |
Pass-through arm name → protobuf field number |
lag_ws.py requires envelope_arms.json to sit beside it; it is used by the req command.
1---2name: liveagent-gateway3description: Drive a LiveAgent instance remotely through its gateway from any agent, shell, or script. Covers the HTTP API, the v2 WebSocket+Protobuf protocol, chat submission and streaming, the multi-agent directory, per-agent credentials, and whitelisted pass-through for filesystem, git, terminal, SFTP, tunnels, memory, cron, skills, settings, history, uploads, and public shares. Use when controlling, querying, automating, scripting, or troubleshooting LiveAgent over its gateway, or when diagnosing gateway connectivity and authentication.4metadata:5 source: https://skillmd.com/skills/drolu/liveagent-gateway6---78# LiveAgent Gateway910Drive a LiveAgent instance remotely over its gateway — from any agent, shell, or program.1112**The gateway is a relay, not an execution environment.** It never runs shell commands, never touches a filesystem, and never stores credentials. It authenticates the caller, applies a whitelist, forwards the request to a desktop *agent*, and relays the answer back. Every privileged action happens on the desktop machine.1314## 1. Required parameters1516Collect these three before anything else. If the caller did not supply them, ask rather than guess.1718| Parameter | Env var | Meaning | How to obtain |19|---|---|---|---|20| Gateway URL | `LAG_GW` | Base URL, with scheme | Deployment output, e.g. `http://localhost:3000`, `https://gw.example.com` |21| Token | `LAG_TOKEN` | Gateway token **or** `agt_…` per-agent token | `LIVEAGENT_GATEWAY_TOKEN` at deploy time, or issued via the admin API |22| Agent ID | `LAG_AGENT` | Which desktop to target | `scripts/lag.sh agents`, or desktop Settings → Remote → Agent ID |2324Port conventions: direct container access uses the mapped host port (commonly `3000`); **behind a reverse proxy use the HTTPS URL and port `443`**.2526If `LAG_AGENT` is unknown, run the `agents` command first — every targeted request needs a non-empty agent id.2728## 2. Which transport to use2930Decide by what the task needs. Most failures come from choosing the wrong one.3132| Need | Transport | Reference |33|---|---|---|34| Health, agent status, credential administration, file upload, public share | **HTTP** (`curl` / PowerShell) | `references/http-api.md` |35| Chat, live events, agent switching | **WebSocket v2** | `references/chat.md` |36| Filesystem, git, terminal, SFTP, tunnels, memory, cron, skills, settings, history | **WebSocket v2 pass-through** | `references/remote-operations.md` |3738HTTP cannot send chat or reach a desktop. WebSocket cannot administer credentials. Use both.3940## 3. Quick start4142```bash43export LAG_GW="http://localhost:3000"44export LAG_TOKEN="<gateway token>"45export LAG_AGENT="agent-<uuid>"4647# HTTP: health, status, directory48bash scripts/lag.sh health49bash scripts/lag.sh status50bash scripts/lag.sh agents5152# WebSocket: handshake, chat, pass-through53python3 scripts/lag_ws.py probe54python3 scripts/lag_ws.py send "list the files in the workspace"55python3 scripts/lag_ws.py req HistoryList --json '{"1":1,"2":20}'56```5758```powershell59$env:LAG_GW="http://localhost:3000"; $env:LAG_TOKEN="<gateway token>"60.\scripts\lag.ps1 health61.\scripts\lag.ps1 agents62.\scripts\lag.ps1 issue-token -Agent "agent-<uuid>" -Name "office-pc"63```6465Both CLIs read `LAG_GW` / `LAG_TOKEN` / `LAG_AGENT`, or accept explicit flags. `lag.sh` uses only `curl`; `lag_ws.py` uses only the Python 3 standard library.6667## 4. Roles and credentials6869Two connection roles exist, and they are not interchangeable:7071| Role | Endpoint | Purpose |72|---|---|---|73| `BROWSER` | `/ws/v2` | The controller — you |74| `AGENT` | `/ws/v2/agent` | The desktop being controlled |7576| Credential | Browser link | Agent link | Admin REST |77|---|---|---|---|78| Gateway token | yes | yes | yes |79| `agt_…` per-agent token | **no** | **only its bound agent** | **no** |8081- A leaked `agt_` token can impersonate **one** machine — never the browser, never the admin API, never other agents.82- `agt_` plaintext is shown **once** at issue time; only a SHA-256 hash is stored.83- **Rotating a credential immediately disconnects that agent.** Warn the operator before rotating.84- Prefer per-agent tokens over sharing the gateway token across machines.8586## 5. Workflow87881. Confirm `LAG_GW`, `LAG_TOKEN`, and (for desktop work) `LAG_AGENT`.892. Verify reachability and auth: `lag.sh health`, then `lag.sh status`.903. If the agent id is unknown, run `lag.sh agents` and pick the intended machine.914. Select the transport from section 2 and open the matching reference.925. Execute the smallest request that answers the question; widen only if needed.936. Report the raw result. Never claim an action succeeded unless a response confirmed it.9495## 6. Guardrails9697- **Never print or log the token.** Pass it by environment variable or an env file with `600` permissions. Avoid command lines where `ps` can read it.98- **`agt_` tokens are bound to one agent.** They cannot reach another machine.99- **Confirm before destructive or mutating calls** — `FsDelete`, `FsRename`, `FsWriteText`, credential rotation/deletion, `MemoryManage`, `CronManage`, `SkillManage`.100- **Never target a host you do not administer.**101- **Do not treat an empty result as a safe result.** Zero agents or an empty event window means *no data returned*, which is not the same as *nothing is wrong*. Confirm `online=true` first.102- **Respect the relay boundary.** If a task needs a tool the gateway does not whitelist, say so instead of improvising.103- **Report failures verbatim.** `401`, close code `4401`, and `local_error` mean different things; see `references/limits-and-errors.md`.104105## 7. References106107- `references/http-api.md` — HTTP endpoints, auth header, admin API, uploads, public shares.108- `references/protocol-v2.md` — handshake, frames, message fields, envelope arm numbers.109- `references/chat.md` — chat submit/edit/cancel, streaming, resume, idempotency, watchdogs.110- `references/remote-operations.md` — filesystem, git, terminal, SFTP, tunnels, memory, cron, skills, settings, history.111- `references/limits-and-errors.md` — size caps, concurrency, close codes, failure modes, recovery.112- `references/deployment.md` — deploying, upgrading, reverse-proxying, hardening a gateway.113114## 8. Scripts115116| File | Language | Purpose |117|---|---|---|118| `scripts/lag.sh` | bash / zsh | HTTP operations via `curl` |119| `scripts/lag.ps1` | Windows PowerShell | HTTP operations via `Invoke-RestMethod` |120| `scripts/lag_ws.py` | Python 3 (stdlib only) | WebSocket v2: handshake, status, agents, chat, pass-through |121| `scripts/envelope_arms.json` | data | Pass-through arm name → protobuf field number |122123`lag_ws.py` requires `envelope_arms.json` to sit beside it; it is used by the `req` command.