OMP Integration

Connect OMP (Oh My Pi) to Capsule Security for complete visibility into AI coding agent activity, including tool execution, sessions, prompts, agent replies and user-run shell and Python - with inline blocking on policy-violating tool calls.

This integration uses OMP's extension system to capture and govern AI coding agent activity. The Capsule extension ships as an OMP plugin, runs in-process inside OMP, forwards every hook event to your Capsule tenant over HTTPS, and applies policy verdicts to tool calls before they execute.

The following hooks are configured:

user_bash and user_python run outside OMP's tool loop and do not accept a verdict, so those commands are audited but not enforced.

Before you begin, ensure you have:

• OMP installed
• A Capsule Security account with admin access
• Network access from your developer machines to your Capsule agentsecurity endpoint (e.g. https://agents.capsule.security)

1. Log in to the Capsule Security portal

2. Navigate to Integrations and locate OMP

3. Click Install - Capsule generates a JWT scoped to your tenant and OMP environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret.

4. Copy the generated token. You will reference it from your Capsule extension configuration in Step 3.

Install the Capsule extension from npm as an OMP plugin:

omp plugin install @capsulesecurity/omp-capsule

To pin a version, use omp plugin install @capsulesecurity/omp-capsule@1.1.0. Run omp plugin list to confirm it is installed.

The Capsule extension reads its settings from ~/.omp/capsule.json:

{
  "endpoint": "https://agents.capsule.security",
  "token": "<token-from-step-1>",
  "blockOnRisk": true,
  "failOpen": true,
  "timeoutMs": 5000,
  "allowConversationAccess": false
}

Every option can also be supplied as an environment variable.

endpoint and token come from the environment when both are set there, otherwise from ~/.omp/capsule.json, and the remaining settings come from that same source. Environment variables still override the other options. A project-level .omp/capsule.json is never read, so cloning an untrusted repository cannot redirect your prompts and tool calls to someone else's server or turn enforcement off.

Without endpoint and token the extension logs a warning and stays inactive. It never breaks the agent loop.

Never commit the JWT to version control. Recommended approaches:

• Keep the token in ~/.omp/capsule.json outside any repository
• Set CAPSULE_TOKEN from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at shell startup
• For MDM-managed deployments, deliver it through the same channel that distributes the OMP configuration

OMP does not rebuild extension modules in place, so /reload-plugins is not enough. Exit any running OMP sessions and start OMP again to load the extension.

1. Start a new OMP session and execute a simple task to generate activity:

   Create a new file called test.txt with the content "Hello World"

2. Log in to the Capsule Security portal

3. Navigate to Inventory > Agents and confirm your OMP agent appears. OMP has no persistent agent identifier, so an agent is identified by the working directory and the user running it.

4. Click on the agent and review the audit logs to verify events are captured:

   • Session start event
   • Tool execution (write tool)
   • The prompt you submitted and the agent reply
   • Session activity

5. To view the full conversation, navigate to Observability and filter by Activity Type - Session (requires allowConversationAccess: true)

If events are not appearing:

1. Verify the endpoint is reachable from the host running OMP:

   curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/health

2. Verify the configuration is found - the extension logs a warning on startup and stays inactive when endpoint or token is missing. Check that ~/.omp/capsule.json is valid JSON.

3. Check for timeouts - if your network has high latency to the Capsule endpoint, increase timeoutMs or confirm failOpen is set appropriately.

4. Confirm the plugin is healthy - run omp plugin doctor, and omp plugin list to check the plugin is enabled.

5. Contact Capsule Security support if issues persist.

The Capsule extension runs in-process inside OMP with full system permissions and observes every tool call, prompt and agent reply. Before deploying:

1. Protect the JWT - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
2. Choose failOpen deliberately - failOpen: true (the default) prioritizes developer productivity; failOpen: false prioritizes policy enforcement and will block tool execution when Capsule is unreachable.
3. Decide on conversation access explicitly - allowConversationAccess: true forwards the model context to Capsule. Enable this only after reviewing the data residency and retention implications with your security and privacy teams.
4. Pin an extension version in production, using omp plugin install @capsulesecurity/omp-capsule@<version>, and review changelogs before upgrading.
5. Use TLS-only endpoints. The extension sends a Bearer token on every request - never configure an http:// endpoint.
6. Understand the coverage boundary - commands run with !, !!, $ or $$ are audited but cannot be blocked.

For help with this integration:

• Email: support@capsule.security
• Include: Your organization ID, integration status, extension version, and any error messages

• OMP Documentation
• OMP Extension API
• OMP Plugins
• Capsule OMP Extension on npm