> For the complete documentation index, see [llms.txt](https://docs.alpha-security.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-security.app/user-guide/engagements.md).

# Engagements

Everything in Alpha is scoped to an engagement. Think of it as a project folder that holds all runs, entities, findings, and reports for a single assessment.

## Creating an engagement

In the web UI, click **New Engagement** on the engagements page. Fill in:

* **Name** - Something descriptive, like "Acme Corp Internal 2026-Q3"
* **Scope** - IP ranges, domains, or a brief description of what's in scope

Only admins can create engagements.

## Switching engagements

The sidebar shows the current engagement name. Click it to switch or go back to the engagement list.

On the collector side, use:

```bash
al engagement list
al engagement set <engagement-id>
```

The active engagement is stored in the collector config. All `al run` and `al query` commands operate within the currently selected engagement.

## Managing access

Operators are assigned to engagements by an admin. Go to **Settings** inside the engagement to add or remove operators.

Roles control what operators can do:

* **admin** has full access everywhere
* **operator** can run tools and manage findings within assigned engagements
* **read\_only** can view data but can't modify anything

## Retention

Admins can set retention policies per engagement. When an engagement is archived, raw output and parsed data remain searchable but the engagement is hidden from the default list.

## Collector tokens

Each engagement has its own collector tokens. Go to **Settings > Collectors** to create, view, or revoke tokens. A token is tied to one engagement and one operator.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alpha-security.app/user-guide/engagements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.