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.

Aegis sits between your AI coding agents and GitHub, intercepting every tool call over the Model Context Protocol (MCP) before it reaches your repositories. This page explains how requests flow through the system, how the policy engine decides what to do, and how rooms and roles control which agents can take which actions.

​
Request lifecycle

Every governed agent action follows the same path:
1

Agent calls a tool

Your coding agent, Claude Code, Cursor, VS Code Copilot, or any MCP-compatible tool, issues a tool call targeting a GitHub action. Common examples include creating a branch, pushing a commit, opening a pull request, or merging one.
2

Aegis intercepts over MCP SSE

The tool call arrives at Aegis via the MCP SSE endpoint at https://app.runaegis.co/sse. Aegis receives the full tool name, arguments, and the user_id header that identifies which account’s policies to apply. No tool call reaches GitHub before Aegis evaluates it.
3

Policy engine evaluates the request

Aegis evaluates the tool call against your enabled policies in order. Policies check things like the target repository, the target branch, the tool being used, and the requesting agent’s role within the room. The engine returns one of four decisions.
4

Decision is enforced

Aegis enforces the decision, executing the action, blocking it, rewriting it, or pausing it for human review, and records the outcome in the audit trail with a timestamp, the tool arguments, and the final result.

​
The four decision types

Every tool call receives exactly one decision. The decision is determined by the first matching policy rule, evaluated in priority order.

ALLOW, action executes immediately

The tool call passes all policy checks and executes against GitHub without any interruption. The agent receives the result and continues normally. ALLOW decisions are logged in the audit trail with a pass policy verdict.Use ALLOW for repositories and operations where your team trusts the agent to act autonomously, for example, a feature branch on a low-risk repository.
The tool call matches a deny rule and is rejected before it reaches GitHub. The agent receives an error response. The action is logged with a DENY decision so you can review what was attempted and why it was blocked.Common deny scenarios include writes to a protected branch, actions on a repository you have set to Deny in permissions, or tool calls that match a specific policy you have enabled.
Aegis modifies the tool call before forwarding it to GitHub. The most common rewrite converts a direct push to a protected branch into a pull request workflow: instead of force-pushing, Aegis opens a PR that a human can review and merge.The agent receives a response reflecting the rewritten outcome, for example, a PR URL rather than a push confirmation. Rewrites are logged with a REWRITE decision and the transformed arguments are visible in the audit trail.
The tool call is held by Aegis and not forwarded to GitHub until a team member approves or denies it from the dashboard. The agent enters a waiting state. Approvals appear in the Approvals section of the dashboard with the full tool name, arguments, a plain-language action summary, and (for PR-related tools) a link to the pull request.A human can approve the action in one click, after which Aegis executes it and returns the result to the agent. If denied, the agent receives an error. All approval events, including who acted and when, are recorded in the audit trail.

​
Policy evaluation

Policies are rules that Aegis evaluates against each incoming tool call. When a tool call arrives, Aegis checks it against every enabled policy in order of priority. The first matching rule determines the decision. If no policy matches, the system falls back to the default permission you set for that repository during onboarding (Allow, Require Approval, or Deny). Policies can match on:
  • The tool name, for example, push_files, create_pull_request, merge_pull_request
  • The target repository, matched against the per-repo permissions you configured
  • The target branch, for example, blocking all writes to main or production
  • The agent role within a room, OWNER, ADMIN, or DEVELOPER each have their own tool-level access controls
Changes to policies take effect immediately for all future tool calls. In-flight approval requests are not retroactively affected.

​
Rooms: the access layer

A room corresponds to a single GitHub repository and is the unit of access control in Aegis. Before an agent can take governed actions on a repository, a room must exist for that repository. Each room has:
  • Members with one of three roles: OWNER, ADMIN, or DEVELOPER
  • Per-tool access controls configured per role, you can allow or deny specific MCP tools for each role independently
  • A room ID and access token used in the MCP configuration to scope the agent’s access to that room
When a tool call arrives, Aegis looks up the room associated with the request, identifies the requesting user’s role in that room, and applies the tool-level access controls for that role before evaluating any higher-level policies.
You must create a room before connecting an agent to a repository in production. The onboarding flow verifies basic MCP connectivity, but full per-repo governance requires a room. See the Rooms documentation for setup details.

​
Dashboard and real-time updates

The Aegis dashboard displays live agent activity, pending approvals, and a summary of recent decisions. The dashboard auto-refreshes every 30 seconds so you always see current data without reloading. Key dashboard views:
ViewWhat you see
ActivityAll recent tool calls with decision, tool name, target repo, and timestamp
ApprovalsPending REQUIRE_APPROVAL actions waiting for your response
Audit trailFull paginated history of every decision, filterable by tool, repo, and date
SessionsTool calls grouped by agent session, with per-session allow/deny/rewrite counts
RoomsRepositories under governance, member roles, and per-role tool permissions

​
Architecture summary

Your agent (Claude Code / Cursor / VS Code Copilot)
        │
        │  MCP tool call (SSE)
        ▼
┌─────────────────────────────────────┐
│           Aegis policy engine       │
│                                     │
│  1. Identify user + room + role     │
│  2. Apply per-role tool controls    │
│  3. Evaluate enabled policies       │
│  4. Return decision                 │
└─────────────┬───────────────────────┘
              │
    ┌─────────┴──────────┐
    │                    │
 ALLOW / REWRITE      DENY / REQUIRE_APPROVAL
    │                    │
    ▼                    ▼
 GitHub API         Block or pause
                    (log + notify)
Every path through the engine produces an entry in the audit trail, regardless of outcome.