Skip to main content

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.

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

Create your account

Go to 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.
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.
2

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, then paste it into the token field.
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.
3

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

Set repository permissions

For each repository you can choose one of three permission levels:
PermissionWhat it means
AllowThe agent can read and write freely. Actions execute immediately without review.
Require ApprovalThe agent can read but all write actions are paused for a human to approve or deny from the dashboard.
DenyAll 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.
5

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.
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 for details. During initial onboarding, the snippet below is all you need to verify connectivity.
Add the following to ~/.claude/mcp.json (or .claude/mcp.json at the project level):
~/.claude/mcp.json
{
  "mcpServers": {
    "aegis-github": {
      "url": "https://app.runaegis.co/sse",
      "headers": {
        "user_id": "YOUR_GITHUB_USER_ID"
      }
    }
  }
}
Then restart Claude Code.
Replace YOUR_GITHUB_USER_ID with the numeric GitHub user ID you provided in step 2.
6

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.
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.
Once the connection is verified, Aegis routes you to the dashboard where you can view live activity, manage approvals, and refine your policies.