> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

Install the Lumos On-Premise Agent, deploy stock and custom connectors, cluster across networks, run multiple agents for high availability, and validate your deployment.

## 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

```bash theme={null}
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](https://gallery.ecr.aws/g3l5j2q0/lumos/on-premise-agent) for tags and the [changelog](/docs/on-prem-agent-changelog). For the full walkthrough (proxies, log collection, ECS/K8s), see the [Installation guide](/integrations/on-premise-agent/installation).

## 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](/docs/connector-sdk-1), 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 theme={null}
   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:

```dockerfile Dockerfile theme={null}
# 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/
```

```bash theme={null}
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:

```toml settings.toml theme={null}
[agent-settings]
cluster_id = "network_a_cluster"
```

```bash theme={null}
# 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](/integrations/on-premise-agent/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](/integrations/on-premise-agent/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.

```mermaid theme={null}
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`:

```toml settings.toml theme={null}
[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:**

```powershell PowerShell · Windows theme={null}
Test-NetConnection -ComputerName integration-proxy.lumos.com -Port 443
```

```bash bash · Docker theme={null}
docker exec -it <CONTAINER_ID> wget --spider https://integration-proxy.lumos.com:443
```

See [Validating Your Deployment](/integrations/on-premise-agent/validating-your-on-premise-agent-deployment).

## Tips and 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

| Topic | Link |
| - | - |
| Installation (Windows and Docker) | [developers.lumos.com/update/docs/installation](/integrations/on-premise-agent/installation) |
| High-availability architecture | [developers.lumos.com/docs/high-availability-architecture](/integrations/on-premise-agent/high-availability-architecture) |
| Clustering | [developers.lumos.com/docs/on-premise-agent-clustering](/integrations/on-premise-agent/on-premise-agent-clustering) |
| Read/write-optimized agents | [developers.lumos.com/docs/configuring-read-and-write-optimized-agents](/integrations/on-premise-agent/configuring-read-and-write-optimized-agents) |
| Validating your deployment | [developers.lumos.com/docs/validating-your-on-premise-agent-deployment](/integrations/on-premise-agent/validating-your-on-premise-agent-deployment) |
| Custom Connector SDK | [developers.lumos.com/docs/custom-connector-sdk](/integrations/connector-sdk/introduction) |
| Agent changelog | [developers.lumos.com/docs/on-prem-agent-changelog](/docs/on-prem-agent-changelog) |