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

# Activate

> Enroll an installed machine with its endpoint key, confirm the first report in Fleet, choose between the observe and managed install modes, and script enrollment on managed installs.

## What this is for

A machine with the agent installed is still local-only. **Activating** it means enrolling it with an
endpoint key so it reports to the console, checking that the first report arrived, and settling
which install mode it runs. This page is for the person doing that on one machine or scripting it
for many.

## Enroll

<Steps>
  <Step title="Issue a key">
    In the console open **Endpoint AI Risk › Fleet › Connect endpoint**, type a **Machine label** and click **Generate key**. Copy the `sk-ep-…` key; it is shown once.
  </Step>

  <Step title="Run the enroll command as the signed-in user">
    ```sh theme={null}
    gw-cli enroll --key sk-ep-… --url https://api.us.guardway.ai --verify
    ```

    The key is stored in that user's agent data folder with owner-only permissions and never logged. `--verify` pushes a first report immediately. The running agent picks the enrollment up on its own; no restart is needed.
  </Step>

  <Step title="Check Fleet">
    The machine appears in **Fleet** within a minute, with the label you gave it, the signed-in user, its OS and agent version. A blank value means the machine has not reported that item yet.
  </Step>
</Steps>

**What the key is.** An endpoint key only enrolls. On enrollment the agent exchanges it for the
machine's own credential, which is valid for one hour and renewed automatically, so the shared key
never reports. Agents older than 0.2.119 keep reporting with the key itself. Revoking the machine's
credential later (**Revoke device access** in Fleet) stops it for good.

**What to run afterwards.** Nothing. The agent keeps scanning and reporting as long as it runs,
which the package arranges at every sign-in. `gw-cli discover --deep --report` pushes a fresh
inventory on demand, and `gw-cli enroll --remove` stops reporting and clears the saved key.

## Managed installs

Enrollment is per user: the key lands in the data folder of whoever runs the command, and a key
written by root is never read by a user's agent. From a deployment tool, run it as the user:

| Tool | How |
| - | - |
| Intune (Windows) | A PowerShell script with **Run this script using the logged-on credentials**, running `& "C:\Program Files\Guardway\gw-cli.exe" enroll --key … --url https://api.us.guardway.ai` |
| Jamf, Kandji (macOS) | A policy or script that runs as the console user, for example through `launchctl asuser` |
| Ansible, Puppet (Linux) | `become_user` or `user =>` set to the developer's account |

On a machine running the managed mode, `gw-cli enroll` targets the running managed agent itself, so
the one command enrolls the machine-wide service as well.

<Warning>
  One key per machine. A key reused across machines makes them indistinguishable in Fleet until each
  has exchanged it for its own credential, and it cannot be revoked for one machine alone.
</Warning>

## Install modes

Every package installs **observe** unless told otherwise. The mode decides what the agent is able
to do on the machine; the console's policy decides what it does.

| | Observe install | Managed install |
| - | - | - |
| Runs as | The signed-in user | A machine-wide service plus each user's agent |
| Inventory, usage, findings | Yes | Yes |
| Live guard | Records only | Can **Block** |
| AI Control switches | Reported | Applied and kept in place |
| Skill custody | No | Yes |
| Enforce posture through your gateway | macOS and Linux: one tool at a time, fail open | Full Enforce, fail open or fail closed |
| Chosen by | The default | macOS: `InstallMode` preference or profile · Linux: `/etc/guardway/install-mode` · Windows: `gw-cli hook --managed` after the install |

Switching an installed machine:

<CodeGroup>
  ```sh macOS / Linux theme={null}
  sudo gw-cli hook --managed      # to managed
  sudo gw-cli hook --observe      # back to observe
  gw-cli hook --installed-mode    # which one is registered
  ```

  ```powershell Windows theme={null}
  & "C:\Program Files\Guardway\gw-cli.exe" hook --managed
  & "C:\Program Files\Guardway\gw-cli.exe" hook --managed --remove
  gw-cli hook --installed-mode
  ```
</CodeGroup>

Both directions are safe while developers are working. Moving back to observe unwires every AI
tool before the service stops, so no open session is left pointing at a service that is gone.

<Tip>
  Roll out in order: install **observe** to everyone, create a policy and leave Live guard on
  **Record** for a week, then move a pilot group to the managed install and switch the policy to
  **Block** or **Enforce** for that group only.
</Tip>

## Break-glass

To stop applying organization policy on one machine without uninstalling, for example while
diagnosing a developer's problem:

```sh theme={null}
sudo gw-cli ai-control break-glass          # stop applying policy on this machine
sudo gw-cli ai-control break-glass --clear  # resume
```

Fleet shows the machine's state, and skill custody stands down while break-glass is on.

## Troubleshooting

| Symptom | Check |
| - | - |
| The machine does not appear in Fleet | `gw-cli enroll --verify` on the machine prints the response. A 4xx means the key was already used or revoked: issue a new one. Allow the hosts on [Network Requirements](/getting-started/network-requirements#endpoint-agent). |
| **Status** shows a last report hours ago | The agent is not running for the signed-in user. `gw-cli hook --status` says what is registered and whether it is up; signing out and in restarts an observe agent. |
| Folders reported unreachable on macOS | Full Disk Access is missing. See [macOS](/endpoint-ai-risk/connect/macos#full-disk-access). |
| **Sensor** shows the machine out of date | Install the current package over it, or set the update policy to **Auto-install**. See [Agent updates](/endpoint-ai-risk/connect/updates). |
| Tray says it cannot reach the agent | Sign out and in, or run `gw-cli hook --status`. The tray only shows the local agent's state and never blocks anything. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.