> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md).

# Activating Shield

Shield is tied to your Xygeni account. Until a valid token is configured, the agent is installed but **inactive**: it does not inspect downloads, scan files or apply any rule, local rules included. `xygeni-fw status` shows `Account: NOT ENROLLED` and the tray app shows only the activation screen.

### Creating the token

Shield needs a **personal API token with the&#x20;*****Xygeni Shield agent*****&#x20;permission**:

1. In the Xygeni dashboard, open **Settings → Security → Personal tokens** and click **Create personal token**.\
   Shortcut: open `/dashboard/settings/security?createToken=shield` in the dashboard, which opens the form with the permission already selected.
2. Select the **Xygeni Shield agent** permission and create the token.
3. Copy the token.

{% hint style="info" %}
Organization tokens cannot hold this permission, and a token created for other uses (for example, CI scans) does not activate Shield unless it also has the *Xygeni Shield agent* permission.
{% endhint %}

### Setting the token

Use whichever option suits you. None of them needs a restart: Shield becomes active within a few seconds.

* **Tray app**: paste the token in the activation screen and click **Activate**. Once active, the token can be changed in **Policy → Xygeni Cloud** (**Save token** / **Clear**).
* **Command line**:

  ```bash
  xygeni-fw config token <token>
  ```

  Run it as the user who installed Shield, or with `sudo` (on Windows, from an elevated terminal).
* **Unattended installations** (MDM, Ansible, golden images): pass the token at install time with `sudo xygeni-fw install --token <token>`, or set it in the `XYGENI_TOKEN` environment variable for `xygeni-fw install`.

The token is checked against Xygeni as soon as it is set. If it lacks the *Xygeni Shield agent* permission it is refused (the command fails, or the tray shows an error) and the previous token, if any, is kept.

To replace the token, set the new one the same way. To remove it, run `xygeni-fw config token ""` or click **Clear** in the tray; Shield goes back to inactive.

### What your subscription enables

What Shield does once activated depends on your Xygeni subscription: the number of **Shield seats** it includes, and whether it includes **centralized configuration**.

| Subscription                             | What you get                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shield with centralized configuration    | **Centrally managed.** Your security team defines the policy in the Xygeni dashboard and Shield applies it automatically. Blocks are reported to the dashboard, the machine is listed in the endpoint inventory and can be isolated remotely. See [Managing Shield from the dashboard](https://docs.xygeni.io/xygeni-products/xygeni-shield/dashboard.md). |
| Shield without centralized configuration | **Locally configured.** Shield protects the machine with the Xygeni malicious packages database and the rules you set on the machine (tray app or command line). There is no central policy, no alerts in the dashboard, no inventory and no remote isolation.                                                                                             |
| No Shield                                | Shield stays inactive, as if it were not installed, and the *Xygeni Shield agent* permission is not offered when creating tokens. Contact your Xygeni account manager.                                                                                                                                                                                     |

In both Shield cases, each active machine uses one Shield seat (see [Shield seats](https://docs.xygeni.io/xygeni-products/xygeni-shield/dashboard.md#shield-seats)).

### Checking the activation state

`xygeni-fw status` shows the state in its `Account:`, `License:` and `Token:` lines:

| Line                                                                                               | Meaning                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Account: enrolled (plan ...) - configuration managed by Xygeni Cloud`                             | Active and centrally managed.                                                                                                                               |
| `Account: enrolled (plan ...) - local configuration only`                                          | Active and locally configured.                                                                                                                              |
| `Account: NOT ENROLLED - no Xygeni token, so nothing is blocked.`                                  | No token yet. Set one as described above.                                                                                                                   |
| `Account: NOT ACTIVE - the server refuses the token, so nothing is blocked.`                       | The token does not have the *Xygeni Shield agent* permission. Create a new one and set it.                                                                  |
| `Account: NOT ACTIVE - Xygeni Shield is not included in this subscription, so nothing is blocked.` | The subscription does not include Shield. Shield activates by itself once it is added.                                                                      |
| `License: active (Shield seat held, lease until ...)`                                              | The machine holds a Shield seat and is fully protected.                                                                                                     |
| `License: DORMANT - ...`                                                                           | No Shield seat is available for this machine right now. See [Shield seats](https://docs.xygeni.io/xygeni-products/xygeni-shield/dashboard.md#shield-seats). |
| `Token: WILL STOP WORKING after ...`                                                               | The token lacks the *Xygeni Shield agent* permission and will be refused after the date shown. Replace it before then.                                      |
| `Token: REJECTED by the server - ...`                                                              | The token has expired or was revoked. Local protection continues, but the central policy, alerts and inventory stop until you set a valid token.            |

The tray app shows the same information: a grey icon and the reason when Shield is not protecting the machine, and a notice in the **Policy** tab when the token needs replacing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
