> ## 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.

# Quickstart

> Create your Aegis account, connect GitHub, set per-repo permissions, and wire up your first AI coding agent via MCP SSE in five minutes.

This guide walks you through everything you need to go from a new account to a governed AI coding agent. The entire flow takes about five minutes and requires no code changes in your agent or repositories.

<Steps>
  <Step title="Create your account">
    Go to [app.runaegis.co](https://app.runaegis.co) and sign up. You can register with your email address and a password, or continue with Google or GitHub OAuth, all three options are available on the sign-up screen.

    After signing up with email, check your inbox for a verification link. You must verify your email before you can log in.

    <Tip>
      If you sign up with GitHub OAuth, your GitHub username is detected automatically. You will still need to provide a personal access token during onboarding.
    </Tip>
  </Step>

  <Step title="Connect your GitHub account">
    The first onboarding step asks for three pieces of information:

    * **GitHub username**, your GitHub handle (for example, `octocat`).
    * **GitHub user ID**, the numeric ID associated with your account. You can find it by visiting `https://api.github.com/users/YOUR_USERNAME` and reading the `id` field.
    * **Personal access token (PAT)**, a classic or fine-grained token with the following scopes:
      * `repo`, full repository access
      * `read:user`, read your profile information
      * `workflow`, update GitHub Actions workflow files

    Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens), then paste it into the token field.

    <Warning>
      Keep your personal access token private. Anyone who holds it can read and write to your repositories within the scopes you granted. Rotate it immediately if it is exposed.
    </Warning>
  </Step>

  <Step title="Sync your repositories">
    After saving your GitHub credentials, Aegis uses your PAT to discover the repositories you own or have access to. Click **Sync repositories** to fetch them.

    Once the sync completes, you will see a list of repositories. All repositories default to **Allow** at this stage, you can change individual permissions in the next step.
  </Step>

  <Step title="Set repository permissions">
    For each repository you can choose one of three permission levels:

    | Permission           | What it means                                                                                                                 |
    | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
    | **Allow**            | The agent can read and write freely. Actions execute immediately without review.                                              |
    | **Require Approval** | The agent can read but all write actions are paused for a human to approve or deny from the dashboard.                        |
    | **Deny**             | All agent access to this repository is blocked. The agent receives an error if it attempts any tool call targeting this repo. |

    You can apply a permission level to all repositories at once using the bulk controls, then override individual repos as needed. You can change these settings at any time from **Settings** inside the dashboard.
  </Step>

  <Step title="Connect your agent">
    Copy the MCP configuration snippet and paste it into your agent's config file. The snippet uses your GitHub user ID as the `user_id` header so Aegis can route requests to the correct account.

    <Note>
      You must create a room in Aegis before connecting an agent in production. Rooms scope governance to a specific repository and generate the `room_id` and `access_token` values used in the full integration config. See the [Rooms documentation](/concepts/rooms) for details. During initial onboarding, the snippet below is all you need to verify connectivity.
    </Note>

    <Tabs>
      <Tab title="Claude Code">
        Add the following to `~/.claude/mcp.json` (or `.claude/mcp.json` at the project level):

        ```json ~/.claude/mcp.json theme={null}
        {
          "mcpServers": {
            "aegis-github": {
              "url": "https://app.runaegis.co/sse",
              "headers": {
                "user_id": "YOUR_GITHUB_USER_ID"
              }
            }
          }
        }
        ```

        Then restart Claude Code.
      </Tab>

      <Tab title="Cursor">
        Add the following to `~/.cursor/mcp.json` (or `.cursor/mcp.json` at the workspace level):

        ```json ~/.cursor/mcp.json theme={null}
        {
          "mcpServers": {
            "aegis-github": {
              "transport": "sse",
              "url": "https://app.runaegis.co/sse",
              "headers": {
                "user_id": "YOUR_GITHUB_USER_ID"
              }
            }
          }
        }
        ```

        Then restart Cursor.
      </Tab>

      <Tab title="VS Code Copilot">
        Create a `.vscode/mcp.json` file in your workspace with the following content:

        ```json .vscode/mcp.json theme={null}
        {
          "servers": {
            "aegis-github": {
              "type": "sse",
              "url": "https://app.runaegis.co/sse",
              "headers": {
                "user_id": "YOUR_GITHUB_USER_ID"
              }
            }
          }
        }
        ```

        Then restart VS Code.
      </Tab>

      <Tab title="Other">
        Point your MCP client at `https://app.runaegis.co/sse` and include a `user_id` header set to your numeric GitHub user ID. Any MCP-compatible agent that supports SSE transport will work.
      </Tab>
    </Tabs>

    Replace `YOUR_GITHUB_USER_ID` with the numeric GitHub user ID you provided in step 2.
  </Step>

  <Step title="Verify the connection">
    After pasting the config and restarting your agent, Aegis waits for the first inbound tool call. The onboarding screen shows a **Waiting for first agent action** indicator that polls every 5 seconds. As soon as your agent hits any MCP tool, the indicator turns green and confirms the connection is working.

    If you want to skip verification for now, you can click **Skip for now** and finish setup. You can always confirm connectivity later from the dashboard.

    <Tip>
      Trigger a simple read-only action in your agent, for example, asking it to list your repositories, to produce the first tool call without risking any writes.
    </Tip>
  </Step>
</Steps>

Once the connection is verified, Aegis routes you to the dashboard where you can view live activity, manage approvals, and refine your policies.