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

# Rooms

> Learn how Aegis rooms work: what they are, how to create and join them, role permissions, tool policies, and how to generate the integration URL.

A **room** in Aegis is a collaborative workspace tied to a single GitHub repository. It groups together the team members who work with that repository, defines what each role is allowed to do via MCP, and produces the integration URL that connects your AI agent to Aegis governance for that repo. Every repository you want to govern with Aegis gets its own room.

## When to create a room

Create one room per GitHub repository you want to govern. If your organization uses three repositories, say, a backend service, a frontend application, and an infrastructure monorepo, you would create three rooms. Each room has its own member list, role assignments, tool permissions, and integration URL.

If you are joining an existing team's room, you do not create one yourself; instead you enter an invite code provided by an OWNER or ADMIN.

## Roles

Rooms have three roles with a strict hierarchy:

| Role        | Level   | Can create invites | Can edit lower roles' tool permissions |
| ----------- | ------- | ------------------ | -------------------------------------- |
| `OWNER`     | Highest | Yes                | Yes (ADMIN and DEVELOPER)              |
| `ADMIN`     | Middle  | Yes                | Yes (DEVELOPER only)                   |
| `DEVELOPER` | Lowest  | No                 | No                                     |

The user who creates a room is automatically assigned the OWNER role. OWNERs and ADMINs can invite new members; DEVELOPERs cannot generate invite links. When viewing tool permissions, you can only edit settings for roles at or below your own level.

## Creating a room

<Steps>
  <Step title="Open the Rooms page">
    Navigate to **Dashboard → Rooms**.
  </Step>

  <Step title="Enter a repository name">
    In the **Create room** card, type the repository name (for example, `my-org/backend`) into the **Repository Name** field.
  </Step>

  <Step title="Create the room">
    Click **Create room**. Aegis creates the room, assigns you the OWNER role, and selects the new room automatically in the sidebar. Your integration URL is generated at this point.
  </Step>
</Steps>

## Joining a room

<Steps>
  <Step title="Obtain an invite code">
    Ask an OWNER or ADMIN of the room to generate an invite link and share the invite code with you.
  </Step>

  <Step title="Open the Rooms page">
    Navigate to **Dashboard → Rooms**.
  </Step>

  <Step title="Enter the invite code">
    In the **Join room** card, paste the invite code into the **Invite code** field and click **Join room**. The room appears in your room list with the role assigned by the invite.
  </Step>
</Steps>

## Generating invite links

OWNERs and ADMINs can generate invite codes from within a room's detail view.

<Steps>
  <Step title="Select your room">
    Click the room in the left sidebar to open its detail view.
  </Step>

  <Step title="Set invite options (optional)">
    In the **Generate invite** form, you can optionally specify:

    * **Max uses**, the maximum number of times the invite code can be used before it expires
    * **Expires at**, a date and time after which the invite code is no longer valid.

    Leave both fields empty to create an invite with unlimited uses and no expiry.
  </Step>

  <Step title="Generate the invite">
    Click **Generate invite**. The invite code appears in the **Invites** panel on the right. Click **Copy** next to the code to copy it to your clipboard and share it with teammates.
  </Step>
</Steps>

<Note>
  Only OWNER and ADMIN roles can see and use the **Generate invite** form. DEVELOPERs see a read-only notice instead.
</Note>

## Tool permissions

Each room has a **tool permissions matrix** that controls which GitHub MCP tools each role is allowed or denied. Permissions are set per-role and apply to every agent connecting to that room with that role.

### Tool groups

MCP tools are organized into four groups:

| Group           | Tools                                                                                                                                                                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Repository**  | `create_or_update_file`, `get_file_contents`, `list_repository_files`, `push_files`, `search_repositories`, `get_repository`                                                                                                                              |
| **Issues & PR** | `create_issue`, `get_issue`, `issue_read:get_comments`, `issue_read:get_sub_issues`, `list_issues`, `create_pull_request`, `get_pull_request`, `pull_request_read:get_comments`, `pull_request_read:get_review_comments`, `pull_request_read:get_reviews` |
| **Search**      | `search_code`, `search_issues`                                                                                                                                                                                                                            |
| **Git**         | `get_latest_commit`, `list_branches`, `create_branch`                                                                                                                                                                                                     |

### Setting tool permissions

<Steps>
  <Step title="Select the role to configure">
    In the **Tool policies** card, use the **View role** dropdown to select the role you want to configure. You can only configure roles at or below your own level.
  </Step>

  <Step title="Allow or deny each tool">
    For each tool in every group, click **Allow** to permit that tool for the selected role, or **Deny** to block it. Changes are saved to the backend immediately, there is no separate save step for tool permissions.
  </Step>
</Steps>

<Warning>
  Tool permissions are enforced in addition to Aegis policies. A tool call that passes tool-permission checks may still be blocked or transformed by a policy. Both layers apply.
</Warning>

## Integration URL

Every room has an integration URL, an SSE endpoint that your AI agent connects to in order to route its MCP tool calls through Aegis governance for that room.

The URL has this structure:

```text theme={null}
https://app.runaegis.co/sse?user_id=<user_id>&room_id=<room_id>&access_token=<access_token>&role=<role>
```

| Parameter      | Description                                            |
| -------------- | ------------------------------------------------------ |
| `user_id`      | Your Aegis user ID                                     |
| `room_id`      | The unique identifier of this room                     |
| `access_token` | Your personal access token for authenticating requests |
| `role`         | The role the agent will act as in this room            |

To copy your integration URL:

<Steps>
  <Step title="Select your room">
    Click the room in the sidebar.
  </Step>

  <Step title="Copy the URL">
    In the room's detail card, click **Copy** next to the **Integration URL** field. Configure your agent to use this URL as its MCP server endpoint.
  </Step>
</Steps>

<Tip>
  Each room member's integration URL is unique to them. Do not share your integration URL, share invite codes instead so teammates can generate their own URLs.
</Tip>