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

# FAQs

## General

### What's the difference between v1alpha1 and v1alpha2?

v1alpha2 adds robust security features for production deployments:

* **Identity Tokens**: Cryptographic session binding and replay prevention.
* **Server-Side Validation**: Centralized policy enforcement via HTTP.
* **Policy Signatures**: Integrity verification for policy files.
* **Tool Schema Hashing**: Protection against tool poisoning.

### Do I need identity tokens?

Not for local development. Identity tokens are recommended when:

* You run agents in a multi-tenant environment.
* You need to audit *who* (which session) performed an action, not just *what* happened.
* You are using the centralized AIP Server.

### How do I set up server-side validation?

1. Enable `spec.server` in your policy.
2. Configure TLS (required for non-localhost).
3. Set `failover_mode` (recommend `fail_closed` for security).
4. See the [Server-Side Validation Guide](../implementations/go-proxy/docs/server-guide.md) for details.

### What is AIP?

AIP (Agent Identity Protocol) is an open standard for secure agentic identity management and authorization starting with a specification for policy-based authorization of AI agent tool calls. It defines how to declare, enforce, and audit what actions an AI agent can perform.

### What's the difference between the AIP specification and the Go proxy?

* **AIP Specification** (`spec/`): The protocol standard that anyone can implement
* **Go Proxy** (`implementations/go-proxy/`): One reference implementation of that standard

Think of it like HTTP (the spec) vs Apache/Nginx (implementations).

### Can I use AIP without the Go proxy?

Yes! AIP is a specification. You can:

* Implement AIP natively in your MCP client (Cursor, Claude Desktop, etc.)
* Build your own proxy in any language
* Use the Go proxy as a reference

### Does AIP require changes to my MCP server?

No. AIP sits between the MCP client and server as a transparent proxy. Your MCP server doesn't need any modifications.

```
[Agent] → [AIP Proxy] → [MCP Server]
```

The proxy intercepts `tools/call` requests, applies policy, and forwards allowed requests unchanged.

## Security

### How is AIP different from workforce AI governance tools like SurePath.ai?

AIP and workforce AI governance tools solve different problems at different layers:

**Workforce AI Governance (e.g., SurePath.ai)**:

* Monitors *employee* AI usage across your organization
* Network/application level visibility
* Answers: "Who in my org is using ChatGPT? What are they asking?"
* Typically SaaS platforms for compliance and governance

**AIP (Agent Identity Protocol)**:

* Controls *what actions AI agents can take* on your infrastructure
* Tool-call level authorization (blocks dangerous operations)
* Answers: "Can this agent delete files? Access production databases?"
* Open protocol for developers building agents

**These are complementary**: Use workforce governance to monitor employee AI usage. Use AIP to secure the agents those employees build. Think of it as different layers—one monitors people, one protects infrastructure.

### How is AIP different from OAuth?

| Aspect      | OAuth                       | AIP                                   |
| ----------- | --------------------------- | ------------------------------------- |
| Granularity | Scope-level ("repo access") | Action-level ("repos.get with org:X") |
| Timing      | Grant-time                  | Runtime (every call)                  |
| Audience    | End users                   | Developers/Security teams             |
| Format      | Token claims                | YAML policy files                     |

OAuth answers "who is this?" AIP answers "should this specific action be allowed?"

### Can AIP prevent all prompt injection attacks?

AIP significantly reduces the blast radius of prompt injection by:

* Limiting which tools an agent can call
* Validating arguments with regex patterns
* Requiring human approval for sensitive operations
* Logging all decisions for forensic analysis

However, AIP cannot prevent prompt injection itself—it mitigates the *consequences*.

### What about network egress? Can a malicious agent exfiltrate data?

Network egress control is planned for AIP v1beta1 (see [spec Appendix D](../spec/aip-v1alpha1.md#appendix-d-future-extensions)). Currently, tool-level authorization is enforced but the MCP server subprocess can still make network calls.

For maximum security today, run MCP servers in containers with `--network=none`.

### Are audit logs tamper-proof?

Audit logs are append-only from the agent's perspective (the agent doesn't have write access to the log file). For production use, forward logs to an external SIEM or use signed logging.

## Policy

### Where do I put my policy file?

Anywhere you like. Common locations:

* `~/.config/aip/policy.yaml` (user config)
* `./agent.yaml` (project root)
* `/etc/aip/policy.yaml` (system-wide)

Pass the path with `--policy /path/to/policy.yaml`.

### What happens if a tool isn't in `allowed_tools`?

It's blocked with error code `-32001 Forbidden`. AIP is **default-deny**.

### Can I test a policy without blocking anything?

Yes! Use monitor mode:

```yaml theme={null}
spec:
  mode: monitor  # Log violations but don't block
```

Check the audit log to see what *would* have been blocked.

### How do I allow a tool but require approval?

Use `action: ask`:

```yaml theme={null}
tool_rules:
  - tool: deploy_production
    action: ask  # Shows native OS dialog
```

### Can I validate tool arguments?

Yes, with regex patterns:

```yaml theme={null}
tool_rules:
  - tool: postgres_query
    allow_args:
      query: "^SELECT\\s+.*"  # Only SELECT queries
```

## Implementation

### My Docker container doesn't stop when I kill the proxy!

When wrapping a Docker container with AIP, signals (SIGTERM/SIGINT) are sent to the `docker` CLI process, not the container itself. This can leave zombie containers running.

**Solution:** Always use `--rm` and `--init` flags:

```bash theme={null}
# Bad - container may not receive signals
aip --policy policy.yaml --target "docker run myimage"

# Good - proper signal handling and cleanup
aip --policy policy.yaml --target "docker run --rm --init -i myimage"
```

| Flag     | Purpose                                                |
| -------- | ------------------------------------------------------ |
| `--rm`   | Automatically remove container when it exits           |
| `--init` | Run init process (tini) that forwards signals properly |
| `-i`     | Keep stdin open for JSON-RPC communication             |

For production deployments, consider running the AIP proxy *inside* the container or using a container orchestrator with proper lifecycle management.

### What MCP clients work with AIP?

Any MCP client that supports custom server commands:

* **Cursor**: Add to `~/.cursor/mcp.json`
* **Claude Desktop**: Add to `claude_desktop_config.json`
* **Continue (VS Code)**: Add to Continue config
* **Custom clients**: Use AIP as the server command

### Does AIP work on Windows?

The Go proxy builds for Windows. Human-in-the-loop (`action: ask`) uses native Windows dialogs via PowerShell.

### How do I debug policy issues?

1. Enable verbose mode: `--verbose`
2. Check stderr for policy decisions
3. Review the audit log: `cat aip-audit.jsonl | jq .`
4. Use monitor mode to test without blocking

### What's the performance overhead?

Minimal. The proxy adds:

* \~1-5ms per request for policy evaluation
* Negligible memory overhead (policies are loaded once)

JSON-RPC parsing and regex matching are fast operations.

## Contributing

### How do I report a security vulnerability?

See [SECURITY.md](../SECURITY.md) for responsible disclosure instructions.

### Can I contribute a new implementation?

Yes! We welcome implementations in other languages. Requirements:

* Pass the conformance test suite (`spec/conformance/`)
* Document your implementation
* Submit a PR to be listed in the registry

### How do I propose changes to the specification?

1. Open an issue describing the change
2. Discuss with maintainers
3. Submit a PR to `spec/AIP-v1alpha1.md`
4. Include conformance tests for new behavior