Node Agent

lattice-node-agent is a host binary, not the main Docker deployment path. It dials out to the server, reports node state, leases reviewed tasks, and posts results. It has no inbound listener.

Download

Linux release artifacts are published from the lattice-node-agent repository:

lattice-agent-linux-amd64
lattice-agent-linux-arm64
SHA256SUMS

Install the matching architecture:

VERSION=v0.2.2
ARCH=amd64
curl -fsSLO "https://github.com/LatticeNet/lattice-node-agent/releases/download/${VERSION}/lattice-agent-linux-${ARCH}"
curl -fsSLO "https://github.com/LatticeNet/lattice-node-agent/releases/download/${VERSION}/SHA256SUMS"
grep "lattice-agent-linux-${ARCH}$" SHA256SUMS | sha256sum -c -
sudo install -m 0755 "lattice-agent-linux-${ARCH}" /usr/local/bin/lattice-agent

For arm64, set ARCH=arm64.

Minimal enrollment

Create the node from the dashboard:

1. Sign in to the Lattice dashboard.
2. Open the Nodes panel.
3. Enter a stable node id such as gmami-jp1.
4. Select Enroll.
5. Copy the generated install script or token before leaving the page.

node-token is a per-node bearer token generated by the server at enrollment time. It is not a GitHub token, Cloudflare token, or operator password. The server stores only a hash of it, so the plain token is shown once. If it is lost, rotate or re-enroll the node and update /etc/lattice/agent.env on that host.

The dashboard install script downloads the matching Linux release artifact, checks SHA256SUMS, installs /usr/local/bin/lattice-agent, writes /etc/lattice/agent.env, and enables lattice-agent.service.

For a quick foreground test, use the printed command:

lattice-agent \
  -server https://lattice.example.com \
  -node-id gmami-jp1 \
  -token '<node-token>'

The token is sent as Authorization: Bearer, not in the JSON request body. Remote cleartext http:// is refused by default.

The foreground command is useful for smoke testing. Use systemd for persistent nodes.

Browser terminal

The dashboard Terminal page uses outbound, agent-side PTY sessions. It is not an inbound SSH server and it does not require storing SSH credentials in Lattice. The agent keeps its no-inbound-listener model: it polls the server for pending sessions, receives input, and posts output back to the dashboard.

The dashboard renders terminal sessions as a dedicated xterm workspace, not as a command input form. Operators can open it from Operations -> Terminal or from an individual node in the Nodes page; the node entry opens /terminal?node_id=... in a new browser tab and starts or resumes that node's latest live session.

Terminal mode requires lattice-agent 0.2.2+ and is off by default. Enable it only on nodes where interactive shell access through Lattice is acceptable:

lattice-agent \
  -server https://lattice.example.com \
  -node-id gmami-jp1 \
  -token '<node-token>' \
  -allow-terminal=true

Equivalent environment variable:

LATTICE_AGENT_ALLOW_TERMINAL=1

Dashboard access requires the terminal:open scope. Initial superuser accounts with * include it. If the agent process runs as root, terminal mode is refused unless -allow-root-exec=true is also set; prefer a dedicated least-privilege service user for nodes where browser terminal access is enabled.

The server keeps live terminal I/O in bounded process memory, not as permanent audit transcripts. It limits each node to four active terminal sessions, expires unaccepted sessions after 10 minutes, expires idle sessions after four hours, and prunes closed transcript buffers after 30 minutes. Open and close events are audited separately. When an operator clicks close, the server immediately marks the session closed and still delivers a close input to the agent so the node-side PTY is torn down on the next poll.

Debug mode

For temporary troubleshooting on the node itself, enable verbose non-secret diagnostics:

lattice-agent \
  -server https://lattice.example.com \
  -node-id gmami-jp1 \
  -token '<node-token>' \
  -debug

The equivalent environment variable is:

LATTICE_AGENT_DEBUG=1

Debug logs include poll-cycle progress, POST paths, payload key names, metric summaries, monitor counts, task IDs, and task exit status. They do not print the node token, task script body, proxy usage secret, or client secret values.

Server-controlled debug

lattice-agent 0.2.1+ also polls a server-owned debug policy from /api/agent/config. From the dashboard, open Nodes -> node detail -> Diagnostics:

• Enable agent debug mode makes the node-agent emit the same non-secret debug lines to the node machine's normal service logs.
• Collect debug lines in server Logs additionally ships those lines back to the server. This is enabled by default when server-controlled debug is turned on. The server stores them under the managed log source agent-debug://<node_id>.
• Disable collection while leaving debug enabled when you want local node diagnostics only.

Equivalent API calls:

# Enable debug and collect centrally (default collect=true).
curl -fsS -b /tmp/lattice.cookies \
  -H "X-Lattice-CSRF: $csrf" \
  -H 'Content-Type: application/json' \
  -d '{"node_id":"gmami-jp1","enabled":true}' \
  https://lattice.example.com/api/nodes/debug

# Keep debug enabled on the node, but do not collect it on the server.
curl -fsS -b /tmp/lattice.cookies \
  -H "X-Lattice-CSRF: $csrf" \
  -H 'Content-Type: application/json' \
  -d '{"node_id":"gmami-jp1","enabled":true,"collect":false}' \
  https://lattice.example.com/api/nodes/debug

# Disable server-controlled debug.
curl -fsS -b /tmp/lattice.cookies \
  -H "X-Lattice-CSRF: $csrf" \
  -H 'Content-Type: application/json' \
  -d '{"node_id":"gmami-jp1","enabled":false}' \
  https://lattice.example.com/api/nodes/debug

If server log storage is disabled, the server still tells the agent to emit local debug logs, but the returned policy disables central collection.

systemd service

Create /etc/systemd/system/lattice-agent.service:

[Unit]
Description=Lattice node agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=-/etc/lattice/agent.env
ExecStart=/usr/local/bin/lattice-agent \
  -server ${LATTICE_SERVER_URL} \
  -node-id ${LATTICE_NODE_ID} \
  -token ${LATTICE_NODE_TOKEN} \
  -log-state-dir /var/lib/lattice-agent/logtail
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target

Create /etc/lattice/agent.env:

LATTICE_SERVER_URL=https://lattice.example.com
LATTICE_NODE_ID=gmami-jp1
LATTICE_NODE_TOKEN=replace-with-node-token
# Optional, for short-lived troubleshooting only:
# LATTICE_AGENT_DEBUG=1
# Optional, high risk: enables dashboard Terminal PTY sessions.
# LATTICE_AGENT_ALLOW_TERMINAL=1

Enable it:

sudo mkdir -p /etc/lattice /var/lib/lattice-agent/logtail
sudo systemctl daemon-reload
sudo systemctl enable --now lattice-agent.service
lattice-agent -version

Privileged operations

Execution is off unless you enable it. Add these only on nodes where reviewed host mutation is acceptable:

ExecStart=/usr/local/bin/lattice-agent \
  -server ${LATTICE_SERVER_URL} \
  -node-id ${LATTICE_NODE_ID} \
  -token ${LATTICE_NODE_TOKEN} \
  -log-state-dir /var/lib/lattice-agent/logtail \
  -allow-exec=true \
  -allow-root-exec=true

LATTICE_NO_EXEC=1 is a kill switch and wins over the enable flags.

Topology and group leaders

Current Lattice node-agent topology is hub-and-spoke:

each node-agent -> primary lattice-server

Every node should point at the primary server URL in -server / LATTICE_SERVER_URL. There is no production group-leader or relay-agent mode in the current protocol. The dashboard role and tags fields are organizational metadata for filtering, planning, and display; they do not make one node forward metrics, tasks, logs, or approvals for other nodes.

If you need regional organization today, use stable node IDs plus tags such as region:jp, group:tokyo, or role:edge. A true leader/child topology must add server-side parent/leader fields, enrollment semantics, health propagation, token-bound delegation, and failure handling before agents can safely point at a leader instead of the primary server.

Server-controlled updates

Agent updates are reviewed server tasks. The update policy uses:

target version + HTTPS binary URL + SHA-256 + install path + service name

For the default service above:

target version: 0.2.2
binary URL: https://github.com/LatticeNet/lattice-node-agent/releases/download/v0.2.2/lattice-agent-linux-amd64
SHA-256: value from SHA256SUMS
install path: /usr/local/bin/lattice-agent
service name: lattice-agent.service

The server downloads the candidate, verifies the SHA-256, requires lattice-agent -version to match the target version, backs up the old binary, installs atomically, and restarts lattice-agent.service after the task result is posted.

Keep auto-plan disabled until the release artifact URL and SHA are final.