Agents, tokens, shell access, and host operations

Loopback’s agent is the on-machine component that connects your servers to the control plane. This page covers tokens, installation, remote shell, and related host actions.

Why agents exist

Agents enable:

Heartbeat and version reporting (feeds reconciliation).
Command channel for maintenance and diagnostics (implementation-specific).
Integration with monitoring sources and update deliveries.

Without an agent, a host may remain unknown or unmanaged beyond raw cloud provisioning.

Agent tokens

Agent tokens are workspace-scoped credentials used when installing the agent. They are not user passwords.

Create a token

You can create tokens with:

Optional description (ops note).
long_living_token flag — short vs long validity semantics per product defaults.

Permission: project.workspace.agent_token (create/list/delete split).

Security

Rotate tokens periodically.
Revoke immediately if a token leaks (treat like a bearer secret).
Limit who can mint tokens — anyone who can creates a path for unauthorized machines to join the workspace fleet.

Installing the agent

The platform serves an install script (e.g. v1/agent/install.sh) that:

Downloads the agent binary for your environment (stable vs unstable update channel depends on deployment).
Configures systemd (on Linux) with:
- API endpoint (production vs staging URL baked into template).
- Token placeholder you replace or pass via environment.
- Optional verbose flags in non-production.

Typical bootstrap

Create agent token in Loopback UI/API.
On the server: run curl … | bash pattern as root (per script instructions).
Verify agent checks in — host transitions to managed states in UI.

Agent updates

Separate update endpoints may deliver version waves via update deliveries reconciled in background.

Shell sessions

Loopback can open interactive shell sessions to hosts through the API (permission: project.workspace.host.shell_session).

Risk

Equivalent to root SSH for many workflows.
Should be rare, logged, and time-bound.

Use break-glass procedures: require ticket ID in metadata, auto-expire sessions, disable for production roles by default.

Host power and hardware actions

Routes exist for power management (on/off/reset classes) where the provider supports it.

Expect async behavior — the cloud API may take time; refresh host status after a minute.

Load-balancer integration on hosts

Files such as WGLB / LBFW / host firewalls integrate hosts into Loopback’s edge or firewall products. Behavior is deployment-specific; ask your operator for the network diagram that matches your workspace.

Hosts & scaling
Reconciliation
Permissions
Your operator publishes the install script under the deployment’s API base URL (path pattern v1/agent/install.sh in the codebase).