> For the complete documentation index, see [llms.txt](https://docs.sec1.io/user-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sec1.io/user-docs/10-siem-edr-xdr/install-the-agent.md).

# Install the Agent

One agent, one install command, for SIEM **and** EDR/XDR. You don't choose a "flavour" — the agent registers with the platform and then does exactly what your **subscription** entitles: log collection (SIEM), endpoint telemetry and response (EDR/XDR) or all of it. The platform pushes the right configuration down; if your subscription changes, the agent adjusts automatically without a reinstall.

A new host appears in the platform within about **30 seconds** of a successful install.

The console is live at [**siem.sec1.ai**](https://siem.sec1.ai) — sign in with your platform credentials (see [Setup & Access](/user-docs/10-siem-edr-xdr/setup-and-access.md)) to manage agents, sources and incidents.

{% hint style="warning" %}
**You copy one token — the enrollment token.** It is shown in the console when you add the agent (**Add data source → Deploy Agent**). Replace `<enrollment token>` in the commands below with that value, and `<YOUR-PLATFORM-URL>` with your Sec1 platform base URL (usually `https://api.sec1.io`).

`SEC1_ENROLL_TOKEN` (`ent_…`) **binds the host** to your team/subscription. During enrollment the agent **automatically obtains its ingest credential** for the telemetry data path — you don't supply a separate ingest token.

Never paste the enrollment token into a shared document or commit it to source control — treat it like a password.
{% endhint %}

## Prerequisites

Check these **before** installing on any host.

### Supported platforms

| OS      | Architectures                        | Notes                                                                           |
| ------- | ------------------------------------ | ------------------------------------------------------------------------------- |
| Windows | x64                                  | Windows 10 / 11 and Windows Server 2016+. PowerShell 5.1+ (built in).           |
| Linux   | amd64, arm64                         | systemd-based distros (Ubuntu, Debian, RHEL/CentOS, Amazon Linux, SUSE).        |
| macOS   | amd64 (Intel), arm64 (Apple Silicon) | Telemetry + software inventory; device enforcement is visibility-only on macOS. |

### Privileges

* **Administrator (Windows) / root (Linux & macOS) is recommended.** The agent installs **system-wide** and **runs at boot** as a service, and host-level enforcement (isolate, USB block, live-response scripts) requires it.
* Without elevation the agent installs **per-user** — it runs only while that user is logged in and cannot perform enforcement actions.

### Network / allowlist

The agent makes **outbound** connections only. It opens **no inbound ports** on the host, and the platform opens no inbound ports for agents. Allow the host to reach these destinations:

| Destination                          | Port        | Purpose                                                        | Direction |
| ------------------------------------ | ----------- | -------------------------------------------------------------- | --------- |
| `api.sec1.io` (the platform gateway) | 443 (HTTPS) | Enroll, heartbeat, policy + command delivery, telemetry ingest | Outbound  |
| `storage.googleapis.com`             | 443 (HTTPS) | Download the agent binary — install time only                  | Outbound  |

These two destinations are all the agent needs to run.

**How the platform reaches the agent (policy + response commands).** The agent keeps an **outbound** connection to `api.sec1.io` and checks in on a short heartbeat (about every 10 seconds). Any policy change or response command an analyst issues is queued on the platform and handed back on the next check-in — so the platform can push configuration, isolate a host, or run a response **without any inbound connection to the endpoint**. This works through NAT, firewalls and proxies unchanged; nothing needs to be opened toward the agent.

**Optional — accepting logs from your existing shippers.** If you want existing shippers (Logstash, Beats, rsyslog) to push logs *into* a Sec1 agent, you can enable a **log receiver** on the agent. This is **off by default** and is the only case where the agent listens on a port:

| Receiver (enable only if used) | Default port            | When to open it                                   |
| ------------------------------ | ----------------------- | ------------------------------------------------- |
| HTTP receiver                  | `9099/tcp`              | Only if a shipper POSTs logs to the agent         |
| Raw TCP receiver               | `9100/tcp`              | Only if a shipper streams logs to the agent       |
| Syslog receiver                | `5514/udp` + `5514/tcp` | Only if devices/shippers send syslog to the agent |

Open a receiver port **only on the internal network** between your shippers and the agent — never toward the internet. Ports are configurable. See [Data collection](/user-docs/10-siem-edr-xdr/data-collection.md).

**Behind a proxy?** The agent honours `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`. For a proxy-only network pass `SEC1_PROXY=http://user:pass@proxy:port` (and `SEC1_CA_FILE=<corp-root-ca.pem>` if the proxy does TLS interception) at install.

### Enrollment token

* The agent needs one token you copy — the **enrollment token** (`SEC1_ENROLL_TOKEN`, `ent_…`), shown in the console when you add the agent (**Add data source → Deploy Agent**). Have it ready — every install command needs it, and keep it private (treat it like a password). It binds the host to your team/subscription, and the platform uses your subscription to decide what the agent does. During enrollment the agent **automatically obtains its ingest credential** for the telemetry data path, so there is no separate ingest token to supply.

### Resource footprint

* Single static binary (\~8–12 MB), no runtime or dependencies to pre-install. Typical usage is low single-digit % CPU and tens of MB RAM. It buffers to a local disk spool if the platform is briefly unreachable, so plan for a few hundred MB of free disk for outage resilience.

***

## Install

Give the agent your **platform URL** and your **enrollment token**. That's it — the agent obtains its ingest credential automatically during enrollment. Everything else (which logs to collect, which collectors to run) is managed centrally from the platform and pushed to the agent.

This is the **single-host** install: one command per machine. To roll out across a fleet, drop the same command into your management tool — see [Single host vs bulk / fleet](#single-host-vs-bulk--fleet).

### Windows (run in an Admin PowerShell)

```powershell
$env:SEC1_PLATFORM_URL = "<YOUR-PLATFORM-URL>"
$env:SEC1_ENROLL_TOKEN = "<enrollment token>"   # binds the host (from the console)
# Which capabilities to enable on THIS host (comma list of siem, edr, xdr).
# Omit to enable everything your subscription allows. Change later in the console.
$env:SEC1_CAPABILITIES = "siem,edr,xdr"
# Optional, for proxy-only networks:
# $env:SEC1_PROXY      = "http://user:pass@proxy:8080"
# $env:SEC1_CA_FILE    = "C:\path\corp-root-ca.pem"
iwr -useb https://storage.googleapis.com/digitalassets-sec1/agent/v0.1.0/install.ps1 | iex
```

### Linux / macOS

```bash
curl -sSL https://storage.googleapis.com/digitalassets-sec1/agent/v0.1.0/install.sh | sudo \
  SEC1_PLATFORM_URL=<YOUR-PLATFORM-URL> \
  SEC1_ENROLL_TOKEN=<enrollment token from the console> \
  SEC1_CAPABILITIES=siem,edr,xdr bash
  # SEC1_ENROLL_TOKEN binds the host; the agent obtains its ingest credential automatically.
  # SEC1_CAPABILITIES is optional — a comma list of siem, edr, xdr for THIS host.
  # Omit it to enable everything your subscription allows; change it later in the console.
  # Examples: a log-only box -> SEC1_CAPABILITIES=siem ; a server -> SEC1_CAPABILITIES=edr,xdr
```

The host appears in the platform within \~30 seconds. **SIEM**, **EDR** and **XDR** capabilities turn on according to your subscription intersected with the per-host toggle — no separate installer, no reinstall if your plan changes. See [Data collection](/user-docs/10-siem-edr-xdr/data-collection.md) for how one agent serves all three.

{% hint style="info" %}
**Choosing capabilities at install (optional).** By default the agent enables everything your subscription allows. To hint the initial choice on a host, pass `SEC1_CAPABILITIES=siem,edr` (a comma list of `siem`, `edr`, `xdr`). This only seeds the per-host toggle — you can change it later in the console, and the effective capability is always your subscription **and** the toggle.

**Capabilities are not the enrollment.** Every host enrolls as **one agent** — there is no separate "SIEM agent" or "XDR agent". `SEC1_CAPABILITIES` (or the console toggle) only decides which functions that one enrolled agent runs. So if you install with `SEC1_CAPABILITIES=xdr` and later want SIEM on that host, you simply **turn SIEM on in the console** — the already-enrolled agent picks it up on its next check-in (seconds), with **no re-enroll and no re-install**. SIEM activates only if your subscription includes it.
{% endhint %}

{% hint style="info" %}
**Configuring what's collected.** Log sources (files, syslog, Windows Event Log channels, HTTP/TCP receivers for existing pipelines like Logstash/Beats) and endpoint collectors are configured in the platform UI (the agent's **Agent Inputs** editor) and pushed to the agent — you don't set them at install time. See [Data collection](/user-docs/10-siem-edr-xdr/data-collection.md).
{% endhint %}

***

## Single host vs bulk / fleet

**Single host** is the command above — set `SEC1_PLATFORM_URL` and `SEC1_ENROLL_TOKEN`, run the one-liner.

**Bulk / fleet** is the *same* command, run by whatever tool you already use to manage machines. The installer is a single non-interactive command, it is idempotent (re-running upgrades in place) and the enrollment token binds every host to the right team — so there is nothing fleet-specific to build. Set the same `SEC1_*` variables and run the one-liner remotely.

**Microsoft Intune / SCCM (Windows):** package the PowerShell command above as a Win32 app or a configuration/PowerShell script. Set the `SEC1_*` env vars at the top of the script.

**Group Policy (Windows):** add the PowerShell command as a computer **Startup script** (runs as SYSTEM, so it installs system-wide).

**Ansible (Linux/macOS):**

```yaml
- hosts: all
  become: true
  tasks:
    - name: Install Sec1 agent
      ansible.builtin.shell: |
        curl -sSL https://storage.googleapis.com/digitalassets-sec1/agent/v0.1.0/install.sh | bash
      environment:
        SEC1_PLATFORM_URL: "{{ sec1_platform }}"
        SEC1_ENROLL_TOKEN: "{{ sec1_enroll_token }}"   # from Ansible Vault, not plaintext
      args: { creates: /usr/local/bin/sec1-edr-agent }
```

**Any RMM / SSH-for-loop** works the same way — the command is idempotent and re-running it upgrades in place.

> Keep the enrollment token in your tool's secret store (Intune secret, Ansible Vault, etc.) — never in a plaintext script committed to source control.

***

## Verify the install

### Self-check (doctor)

The agent ships a built-in diagnostic. Run the agent binary with `-doctor` to validate connectivity, configuration and permissions:

```bash
sec1-agent -doctor -config <path-to-config>
```

It reports whether the agent can reach the platform, whether the token is accepted and whether it has the access it needs to collect.

### Agent logs

* **Windows:** `C:\Program Files\Sec1Agent\agent.log` (or `%LOCALAPPDATA%\Sec1Agent\` for a per-user install)
* **Linux:** `journalctl -u sec1-agent`

### In the platform

The same host surfaces wherever its subscription applies:

* Endpoint telemetry (EDR/XDR): **XDR → Endpoints**
* Log sources (SIEM): **SIEM → Sources**

If a host does not appear within a minute, re-run the `-doctor` check and review the agent log for connection or token errors.