---
title: "Deploy the agent at scale"
description: "Enroll many computers with staged rollout installers, the Windows MSI in Group Policy or Intune, token-only enrollment, golden images, and proxies."
url: "https://support.outpostplatform.com/agent/deploy-at-scale/"
product: "agent"
type: "how-to"
status: "draft"
ai_summary: "Mass deployment of the Outpost agent. Staged rollout makes one installer reusable for 1 to 90 days and 1 to 1000 machines. The MSI needs agent.json beside it; SKIPCONFIG=1 skips it. The single-file exe takes --dangerously-silent-installation. Issue token only gives a single-use 24-hour token for outpost-agent enroll. outpost-agent reset prepares golden images. Proxy field sets an HTTP proxy."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "enroll:manage"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/agent/deploy-at-scale.md"
license: "CC BY 4.0"
---

# Deploy the agent at scale

This page covers the ways to enroll more than a handful of computers: one
installer reused across a rollout, the Windows MSI in a deployment tool, a bare
enrollment token for scripted installs, and golden images. Each section stands
on its own. For one computer at a time, see
[Install and enroll the agent](/agent/install-and-enrollment/).

## Before you begin

- You need the `enroll:manage` permission.
- Your deployment tool must run installers with administrator rights (Windows)
  or as root (Linux, FreeBSD, OpenBSD).
- Each endpoint counts toward your plan's endpoint limit. Home Lab allows up to
  15 managed endpoints and Essentials up to 50. During a free trial, Enterprise
  and MSP allow up to 100. See [Plans and limits](/account/plans-and-limits/).

:::caution
A staged rollout installer can enroll computers into your Outpost until it
expires or runs out of uses. Store it where you store your other deployment
packages, and never on a public share.
:::

## Use one installer for a rollout {#staged-rollout}

An installer downloaded with the default settings enrolls one computer within
24 hours. A staged rollout installer carries a token that many computers can
use over a longer period, so it can sit in your deployment tool for the whole
rollout.

1. Go to **Endpoints** > **All endpoints** and select **Enroll a device**.
2. Choose the **Site** and **Platform**.
3. Select **Staged rollout: reuse this installer on many machines over time**.
4. In **Valid for (days)**, enter how long the installer can enroll computers,
   from 1 to 90. The default is 30.
5. In **Machines**, enter how many computers it can enroll, from 1 to 1000.
   The default is 50.
6. Select **Download installer**.

Every computer that runs the installer joins the site you chose. To enroll
computers into different sites, download one installer per site.

## Deploy the Windows MSI {#windows-msi}

Choose **Windows x64 (MSI, for GPO or Intune)** as the platform. The download
is a `.zip` holding two files:

| File | What it is |
| --- | --- |
| `outpost-agent-setup.msi` | The signed MSI. It is the same file for every customer. |
| `agent.json` | This client's connection settings and enrollment token. |

The MSI reads `agent.json` from the folder it runs from. If the file is not
there, the install stops before it changes anything, with:

```text
agent.json was not found next to this installer. Extract the whole download (the .msi and agent.json together) and run the .msi from that folder, or pass SKIPCONFIG=1 to install without a configuration.
```

So whichever tool you use, deploy the two files together:

- **Group Policy:** put both files in the same folder on the share your
  software installation policy points at.
- **Intune:** package both files together as one app, for example as a Win32
  app, and install with `msiexec /i outpost-agent-setup.msi /qn`. An app that
  uploads only the `.msi` cannot enroll.

The MSI installs the agent, the watchdog, and the tray app in
`C:\Program Files\Outpost\Agent`, and starts the services.

### MSI properties

| Property | Effect |
| --- | --- |
| `SKIPCONFIG=1` | Installs without reading `agent.json`. The agent does not enroll until you give it a token. See [Enroll with a token](#token-only). |

The MSI shows no user interface and no consent panel.

### After the first install

The MSI is for the first install. After that, the agent updates itself, so
the list of installed programs in Windows goes on showing the version the MSI
installed. Running a newer MSI over an installed agent upgrades it in place and
keeps its enrollment. Like a first install, it needs `agent.json` beside it, or
`SKIPCONFIG=1`.

## Run the single-file installer silently {#silent-exe}

The single-file installer (`outpost-agent-<client-id>-setup.exe`) normally shows the consent panel and waits for the
person at the computer to type `AGREE`. From a deployment tool that you
control, skip the panel:

```powershell
.\outpost-agent-<client-id>-setup.exe --dangerously-silent-installation
```

The installer returns one of these exit codes:

| Code | Meaning |
| --- | --- |
| `0` | Installed. |
| `1` | The person at the computer declined at the consent panel. |
| `2` | Bad command-line arguments. |
| `3` | The installer's payload is missing or unreadable. |
| `4` | The installer's configuration is missing or unusable. Download it again. |
| `5` | The install failed. |
| `6` | The installer was not run with administrator rights. |

The installer writes a log to `outpost-setup.log` in the temporary folder of
the account that ran it. See [Agent command reference](/agent/cli/#setup-exe)
for every option.

:::danger
Skipping the consent panel means nobody at the computer is told that it is
being placed under remote management. Use
`--dangerously-silent-installation` only on computers your organization owns
or manages under an agreement.
:::

## Enroll with a token {#token-only}

Use a bare token when the agent is already installed but not enrolled: an MSI
installed with `SKIPCONFIG=1`, a single-file install with `--skip-config`, or
a golden image prepared with `outpost-agent reset`.

1. Go to **Endpoints** > **All endpoints** and select **Enroll a device**.
2. Choose the **Site**.
3. Select **Issue token only**.
4. Copy the token. The console shows it once and cannot show it again. The
   token enrolls one computer and expires after 24 hours.
5. On the computer, as an administrator or root, run the command the console
   shows under **Then run on the device**:

   ```sh
   outpost-agent enroll --server <your-server-url> --token <enrollment-token>
   ```

   On Windows the agent is `C:\Program Files\Outpost\Agent\outpost-agent.exe`.
   On Linux, FreeBSD, and OpenBSD it is `/opt/outpost/outpost-agent`.
6. Restart the agent service so it connects with its new identity.

On a Linux, FreeBSD, or OpenBSD computer where the agent binary is present but
not yet installed as a service, `install` takes the same flags and enrolls and
installs in one step:

```sh
sudo /opt/outpost/outpost-agent install --server <your-server-url> --token <enrollment-token>
```

## Prepare a golden image {#golden-images}

Computers deployed from one image must not share the image's enrollment.
Before you capture an image of a computer that has the agent, strip its
identity:

1. On the template computer, as an administrator or root, see what would
   change:

   ```sh
   outpost-agent reset
   ```

   Without `--force`, `reset` only reports.
2. Apply it. To have every computer from the image enroll itself on first
   boot, add a token from a [staged rollout](#staged-rollout) or
   **Issue token only**:

   ```sh
   outpost-agent reset --force --token <enrollment-token>
   ```

   Without `--token`, enroll each deployed computer by hand afterwards.
3. Capture the image.

`reset` removes the certificate, private key, and pinned server certificate,
and clears the endpoint's identity from its configuration. It keeps the server
address and the reporting intervals.

## Apply connection settings on Linux, FreeBSD, and OpenBSD {#import-config}

The `agent.json` in a downloaded tarball holds the connection settings. You can
apply one to an agent that is already installed, for example to move a
computer to another client:

```sh
sudo /opt/outpost/outpost-agent import-config agent.json
```

- If the computer is already enrolled to the client the file names, nothing
  changes.
- If it is enrolled to a different client, the old identity is removed and the
  computer enrolls into the new one.
- The file is deleted after it is applied, because it holds an enrollment
  token.

Restart the service afterwards.

## Proxies {#proxies}

If computers reach the internet through an HTTP proxy, enter it in **Proxy
(optional)** before you select **Download installer**, as an `http://` or
`https://` URL such as `http://proxy.example.com:8080`. The agent uses it for
its outbound connections.

A proxy set in the agent's environment takes precedence over the one in the
installer. The agent reads `HTTPS_PROXY`, so you can set the proxy per
computer.

On Linux, put it in `/etc/default/outpost-agent`, which the service reads at
start, and restart the service:

```sh
HTTPS_PROXY=http://proxy.example.com:8080
```

The proxy must allow HTTPS connections through to your Outpost on port 443.

## Verify

1. Go to **Endpoints** > **All endpoints**.
2. Check that the computers you deployed to appear.
3. Select the **Never reported in** view to find endpoints that enrolled but
   have not sent inventory yet.

## Next steps

- [Agent command reference](/agent/cli/)
- [Agent and tray updates](/agent/updates/)
- [Troubleshoot the agent](/agent/troubleshooting/)