Configuration

Agent Keeper configuration depends on which agent surface you are securing. Claude Code uses settings.json hooks. Cursor, Windsurf, and GitHub Copilot Agent Mode use local hook scripts. Claude Cowork uses the MCP gateway.

Examples use https://YOUR_AGENTKEEPER_URL as the app origin. Replace it with the URL of your Agent Keeper deployment.

Claude Code hooks configuration

The hooks are configured in ~/.claude/settings.json. This file tells Claude Code to send tool calls to Agent Keeper for evaluation before execution, log completed tool calls to the audit trail, and register sessions on startup.

Hook endpoints

Agent Keeper uses four Claude Code hook events:

All four endpoints are fail-open: if the Agent Keeper server is unreachable or returns an error, Claude Code continues normally.

Matcher patterns

Each hook entry includes a matcher field that controls which tools or events trigger the hook:

• UserPromptSubmit: *, fires on every user prompt submission.
• PreToolUse / PostToolUse: Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch, matches the core file-system, shell, and web tools. MCP skill calls (mcp__server__tool) are also caught because they pass through the tool pipeline.
• SessionStart: *, fires on every new session.

API key

• Obtained from Settings > API Keys in the dashboard.
• Starts with ak_live_.
• Write-only: can only send events and check policies. Cannot read back data, list hosts, or access scan results.
• Safe to commit to repos (similar to a Sentry DSN).

Timeout

The timeout field is set to 10 seconds by default. If the endpoint does not respond within this window, Claude Code treats it as a pass and continues execution. This fail-open behavior ensures Agent Keeper never blocks your workflow due to network issues.

Configuration methods

There are five ways to get the hooks into settings.json:

1. Plugin command: run /agentkeeper:connect inside Claude Code. The plugin writes the hooks JSON for you.
2. Manual: copy the JSON block below into ~/.claude/settings.json.
3. GitHub Integration: Agent Keeper auto-opens a PR that adds .claude/settings.json to your repo. See GitHub Integration.
4. MDM (JAMF / Intune / Kandji): deploy settings.json to managed workstations via a configuration profile. See JAMF Deployment.
5. Project-level: commit .claude/settings.json to a repo. Claude Code merges project settings with user settings, so hooks apply to anyone working in that repo.

Example settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://YOUR_AGENTKEEPER_URL/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch",
        "hooks": [
          {
            "type": "http",
            "url": "https://YOUR_AGENTKEEPER_URL/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch",
        "hooks": [
          {
            "type": "http",
            "url": "https://YOUR_AGENTKEEPER_URL/api/v1/claude-code/audit",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://YOUR_AGENTKEEPER_URL/api/v1/claude-code/checkin",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Replace ak_live_YOUR_KEY with your actual API key from the Settings page.

Multi-agent hook installer

The hook installer wires Cursor, Windsurf, GitHub Copilot Agent Mode, Codex, and Gemini CLI to the unified policy endpoint:

export AGENTKEEPER_API_URL="https://YOUR_AGENTKEEPER_URL"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh")

You can target one IDE:

bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide cursor
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide windsurf
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide copilot
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide codex
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide gemini

The installer stores the API key in ~/.agentkeeper/config and installs the appropriate hook file for the selected tool.

API key

The AGENTKEEPER_API_KEY environment variable connects local hooks and gateways to the web dashboard.

export AGENTKEEPER_API_KEY="ak_live_..."

You can get an API key from the Settings page in the dashboard after creating an account.

Local config files

The hook installer stores its configuration in ~/.agentkeeper/:

The MCP gateway stores its configuration in ~/.config/agentkeeper-mcp-gateway/config.json. See MCP Gateway for gateway-specific options.

Notification settings

Paid plan users can configure notifications in the dashboard. Email alerts are available on Pro, Team, and Enterprise plans. Webhook alerts require a Team or Enterprise plan. When the agent reports a scan with critical findings, the system can automatically alert you.

Notifications are configured in Settings > Notifications in the dashboard.

Environment variables