Agent Quick Start Guide

What it is

The On-Premise Agent is a lightweight, stateless, headless service that runs inside your network and acts as a secure bridge between systems behind your firewall (Active Directory / LDAP, databases, internal apps) and the Lumos cloud. It makes outbound-only connections (HTTPS on port 443 to integration-proxy.lumos.com), so you never expose internal systems to the internet.

Prerequisites

• Host: Windows Server 2016+ (x86-64) or a container runtime (Docker, ECS, Cloud Run, Azure Container Instances). ARM is not supported.
• Hardware: 16 GB RAM, 64 GB storage to start. High-volume deployments (large directory syncs, many connectors on one host, or frequent provisioning) need more CPU, RAM, and storage; size these with Lumos (see When to run additional agents, below).
• Outbound egress: HTTPS/443 to https://integration-proxy.lumos.com.
• Internal reachability: the ports of the systems you'll connect to (e.g. 636 for LDAPS, 1433 for SQL Server).

1. Get your API key

Use one token per agent.

1. Go to Settings → API Tokens (app.lumosidentity.com/settings/api_tokens).
2. Click Add Token → On Prem Agent Token.
3. Copy the token and set it as the environment variable LUMOS_ON_PREMISE_AGENT_API_KEY on the agent host.

👍

Recommendation

Mint a separate token for each agent rather than sharing one across the fleet. One token per agent lets you:

• Rotate or revoke one agent without disrupting any of the others.
• Contain blast radius: if a host is compromised, you disable just that one token.
• Attribute activity per agent more cleanly.

To rotate a token: create a new On Prem Agent Token → update that agent's LUMOS_ON_PREMISE_AGENT_API_KEY → restart the agent → delete the old token.

📘

Good to know

• The token must be of type On Prem Agent; a regular Lumos API key is rejected.
• The token is domain-scoped: it determines which Lumos domain/environment this agent (and its connectors) shows up in. Pointing an agent at a different environment is just a matter of swapping in that environment's token and restarting.
• The key must stay on the host for the agent to authenticate every request, so secure the host with least-privilege access. If a key leaks, exposure is limited to that one on-prem integration surface, and it does not grant Lumos admin access.

2. Install the agent

Windows (service)

1. Set LUMOS_ON_PREMISE_AGENT_API_KEY as a System environment variable.
2. Download the agent ZIP from Lumos, extract it to a folder (e.g. C:\lumos-on-premise).
3. In an Administrator PowerShell in that folder, run .\lumos-agent.exe install.
4. In Services (services.msc), open Lumos Agent Service:
   • Startup type: Automatic (Delayed Start).
   • Recovery tab: set First failure, Second failure, and Subsequent failures all to Restart the Service; set Restart service after to 1 minute and Reset fail count after to 1 day.
   • Click Start.

Docker / containers

docker run --platform linux/amd64 -d \
  --restart unless-stopped \
  -e LUMOS_ON_PREMISE_AGENT_API_KEY=$LUMOS_ON_PREMISE_AGENT_API_KEY \
  public.ecr.aws/g3l5j2q0/lumos/on-premise-agent:latest

📘

Tip

Pin the image tag (e.g. ...on-premise-agent:0.1.0) instead of latest to avoid surprise updates. See the ECR gallery for tags and the changelog. For the full walkthrough (proxies, log collection, ECS/K8s), see the Installation guide.

3. Deploy connectors

Stock connectors

• Docker: the default image already bundles all connectors, so there's nothing extra to do. If you'd rather start empty and add only the connectors you need (or bake in your own custom connectors), Lumos also publishes a connector-less image at public.ecr.aws/g3l5j2q0/lumos/on-premise-agent-no-connectors.
• Windows: in the integration setup wizard, download the connector ZIP, drop it into the agent's connectors/ folder, and restart the agent. Do not unzip it; the agent unpacks connectors automatically at runtime. Allow a few minutes for the connector to appear in Lumos.

Custom connectors

Build with the Connector SDK, then compile and drop the archive onto the agent:

1. Scaffold / build: connector scaffold <name> <dir> and implement your capabilities.

2. Compile for on-prem:

   Bash

   connector compile-on-prem --connector-root-module-dir <dir> --app-id <app-id>

   This produces an archive (.tar.gz on Linux, .zip on Windows) containing the connector executable, its _internal/ runtime folder, and a metadata.toml, all at the archive root.

3. Deploy: drop the archive into the agent's connectors/ folder (don't unzip) and restart. It appears under Integrations → Agents; connect it with credentials.

🚧

Gotcha

Compile for the target platform. For the Docker agent, that's Linux amd64. A connector built for the wrong platform won't run.

Bake a custom connector into an agent image

For immutable, orchestrated deployments (ECS, Kubernetes, etc.), you can build your custom connector into a container image instead of dropping it into a running agent. Build a small image from the official agent image and copy the compiled archive into the agent's connectors directory:

# Pin the base tag; build for linux/amd64 (ARM is unsupported)
FROM public.ecr.aws/g3l5j2q0/lumos/on-premise-agent:0.1.0
# Archive from `connector compile-on-prem` (Linux -> .tar.gz). Do not unzip it.
COPY my_custom_app_x86_64.tar.gz /onprem/agent/connectors/

docker build --platform linux/amd64 -t my-lumos-agent:0.1.0 .

docker run --platform linux/amd64 -d --restart unless-stopped \
  -e LUMOS_ON_PREMISE_AGENT_API_KEY=$LUMOS_ON_PREMISE_AGENT_API_KEY \
  my-lumos-agent:0.1.0

• Compile for linux/amd64. The same platform gotcha applies. Leave the archive as .tar.gz; the agent unpacks it at runtime.
• The stock connectors stay bundled in the base image; your COPY just adds to them.
• The connector still shows up in whichever domain/environment the runtime token (LUMOS_ON_PREMISE_AGENT_API_KEY) authenticates to, so the same image can serve multiple environments by swapping the token; no rebuild needed to move test → prod.
• Pin the base image tag and rebuild on a newer base to pick up agent + stock-connector updates.
• Baking survives container recreation, which is why it's preferred over a volume-mounted drop-in for immutable/auto-scaling deployments.

4. Clustering (multiple networks)

A cluster is a group of agents that share network reachability to the same set of applications. If you run more than one agent, especially across separate networks, use clusters so Lumos routes each operation to an agent that can actually reach the target.

Assign a Cluster ID via settings.toml or an environment variable, then restart:

[agent-settings]
cluster_id = "network_a_cluster"

# equivalently, as an environment variable
LUMOS_ON_PREMISE_AGENT_CLUSTER_ID=network_a_cluster

When connecting (or reconnecting) an integration, select the cluster in the connection settings. An agent with no Cluster ID belongs to the default cluster.

🚧

Important

• An agent only picks up operations for the connectors it actually has. But when the same connector runs on agents in different networks, you must use Cluster IDs; otherwise routing between them is effectively arbitrary and operations can land on an agent that can't reach the target.
• Each integration maps to exactly one cluster, with no automatic cross-cluster failover. Choose the cluster deliberately per integration.
• Retire stale dev/test agents. An old agent left running on a different Cluster ID can silently pick up (and drop) operations meant for that cluster.

More detail: On-Premise Agent Clustering.

5. When to run additional agents

Add agents for redundancy and network reach, not as a simple throughput dial.

• High availability: run at least 2 agents, ideally in separate availability zones or data centers. Within a cluster, Lumos Cloud distributes work across the healthy agents and routes around one that goes offline, so you don't need your own load balancer. Put your HA agents in the same cluster (agents with no Cluster ID all share the "default" cluster) and give each the same set of connectors so either can serve the workload. See High-Availability Architecture.
• Network reach: deploy an agent in each isolated network and route to it with a Cluster ID (above).
• Isolate a high-traffic connector: a connector expected to handle heavy load (large directory syncs or frequent provisioning across all its integrations) can run on its own dedicated agent so its workload doesn't slow down other connectors. No clustering is required: because an agent only picks up operations for the connectors installed on it, giving a busy connector a dedicated agent (with only that connector deployed) isolates it automatically.
• Isolate a high-traffic integration: when a single integration is the hot spot (for example one very large Active Directory domain while the same connector also serves smaller AD integrations), give it a dedicated agent in its own cluster and assign that integration to that cluster. This pins the heavy integration to hardware you've sized for it without affecting the other integrations that share the same connector.
• Read/write separation: set LUMOS_ON_PREMISE_AGENT_OPERATION_MODE to read_preferred or write_preferred (default is default = both). This is a preference that keeps long-running reads from blocking writes, with a fail-safe: if no capable agent exists in the cluster, any agent will run the operation. Treat it as isolation, not a scaling lever.

📘

On scale

Additional agents provide redundancy and reach, not a linear throughput multiplier. For high-volume workloads, coordinate with Lumos on sizing. The Docker/Linux agent scales more flexibly than the Windows agent, and max-concurrent-operations is an advanced tuning knob if needed.

flowchart LR
  subgraph network["Your network"]
    A1["Agent 1<br/>(Active Directory connector)"]
    A2["Agent 2<br/>(other Lumos-built connectors)"]
    A3["Agent 3<br/>(custom connectors)"]
    AD["Active Directory"]
    APPS["Other on-prem apps and DBs"]
    SYS["Internal / custom systems"]
    A1 --> AD
    A2 --> APPS
    A3 --> SYS
  end
  CLOUD["Lumos Cloud"]
  A1 -. "HTTPS 443" .-> CLOUD
  A2 -. "HTTPS 443" .-> CLOUD
  A3 -. "HTTPS 443" .-> CLOUD

Each agent runs only the connectors it needs and reaches only its own systems; a heavy connector (here, Active Directory) sits on its own agent so its load can't affect the others.

🚧

Rolling upgrades

A new agent can take ~15 minutes to initialize. To avoid failed syncs/provisioning during an update, always keep at least one agent per cluster running with all the connectors you use. Upgrade one agent at a time, validate it in the UI, then move to the next.

One caveat: if an agent release changes behavior or functionality, a fleet running mixed versions mid-rollout can briefly behave inconsistently, but that's inherent to any rolling upgrade, however you structure high availability, not specific to this setup.

6. Validate the deployment

• Lumos UI: go to Integrations → Agents. A healthy agent shows Connected, its Cluster ID, and its connector versions.
• Local info endpoint (optional): enable the agent's HTTP server and hit /info:

[agent-settings]
http-enable-server = true
http-server-port = 10002

(Set LUMOS_ON_PREMISE_AGENT_HTTP_ENABLE_SERVER / ..._HTTP_SERVER_PORT via env vars, and publish the port if running in Docker.) It reports connected, domain_name, cluster_id, operation_mode, connectors, and version.

• Firewall test: open integration-proxy.lumos.com/external/firewall-test. Endpoint not found means traffic is reaching Lumos (good); no response means a firewall issue.
• Connectivity checks:

Test-NetConnection -ComputerName integration-proxy.lumos.com -Port 443

docker exec -it <CONTAINER_ID> wget --spider https://integration-proxy.lumos.com:443

See Validating Your Deployment.

Tips & troubleshooting

• Pin your Docker image version to control when connector/OS updates land.
• Logs: control verbosity with LUMOS_ON_PREMISE_AGENT_LOG_LEVEL (e.g. DEBUG); set LUMOS_LOG_TO_STDOUT=true to send logs to stdout for CloudWatch/log collectors; set LUMOS_ON_PREMISE_AGENT_SEND_CRITICAL_LOGS_TO_LUMOS=true to forward sanitized error-level logs to Lumos for support (off by default).
• Behind a corporate proxy: set HTTP_PROXY / HTTPS_PROXY on the host/container.
• Don't rename, move, or unzip the connectors/ or DO-NOT-TOUCH folders; the agent manages them.
• 401 Unauthorized on startup → the token is invalid or the wrong type. Create a new On Prem Agent Token and update LUMOS_ON_PREMISE_AGENT_API_KEY.
• 404 .../operations/arguments → the connector isn't present on the agent that picked up the operation. Confirm the connector is deployed on an agent in the right cluster.

Reference