AI Agent Integrations

RunEnv Agent Guard lets coding agents perform approved, auditable actions without receiving general secret-read access or connector credentials. The recommended workflow is give agents actions, not secrets.

Use Agent Guard when an agent needs to work with a configured external action, such as a repository or operational connector. Use the normal CLI or SDK for a human-operated application runtime; do not copy a service token into an agent configuration.

Before you connect

  1. Run runenv agent doctor . to scan the current workspace locally for likely credential exposure. This is local by default and does not require an account.
  2. Sign in as the human sponsor with runenv login.
  3. Choose the target RunEnv project ID. Agent authorization is project-bound.

Connect a supported coding agent

RunEnv supports codex, claude, copilot, and cursor adapters. Start with a preview:

runenv agent connect codex --project <project-id>

The preview lists the configuration files that would change. Apply only after reviewing it and completing browser OAuth:

runenv agent connect codex --project <project-id> --yes

The CLI uses OAuth authorization-code flow with PKCE S256. It stores the resulting profile in the operating system credential store and refreshes tokens through the documented OAuth flow. Use the rollback command if you need to undo an applied adapter change:

runenv agent rollback <run-id>

Custom MCP clients

For a compatible local MCP client, configure a stdio server after the human sponsor has connected the project:

{
  "mcpServers": {
    "runenv-agent-guard": {
      "command": "runenv",
      "args": ["agent", "mcp", "stdio", "--project", "<project-id>"]
    }
  }
}

The local server exposes only these brokered action tools:

  • runenv_list_capabilities
  • runenv_preview_action
  • runenv_request_permit
  • runenv_execute_action
  • runenv_get_action_status
  • runenv_cancel_action
  • runenv_rollback_action

Every canonical tool validates its response against an exact, bounded output contract. Unknown fields and unredacted credential-shaped fields fail closed with a generic tool error; they are never passed through by heuristic redaction. There is no raw secret retrieval tool in the Agent Guard MCP surface.

Action arguments must be a JSON object. The complete serialized object is limited to 64 KB, nesting depth to 8, each object or array to 200 entries, each string to 4,000 characters, and each key to 128 characters. Fields shaped like secrets, passwords, credentials, tokens, authorization values, signatures, or sensitive keys may contain only the literal [REDACTED] marker. An agent cannot use action arguments to supply an unredacted credential.

For a v1 action preview, RunEnv derives the canonical target from the scoped connector configuration and validated arguments before policy evaluation. The optional resource field is only an exact caller assertion; if it is sent, it must match the derived target. Clients should omit it when the canonical target has not already come from trusted RunEnv output rather than guessing a connector-specific identifier.

Remote clients and API discovery

Remote Streamable HTTP MCP is available at /api/mcp/agent-guard. A client must first complete the Agent Guard OAuth flow and request only the scopes it needs.

Send Content-Type: application/json and an Accept header containing both application/json and text/event-stream. After initialization, send the negotiated MCP-Protocol-Version value. Requests are limited to 1 MB and each POST must contain exactly one JSON-RPC message; batch arrays are rejected. All transport responses are non-cacheable.

Use these discovery documents instead of hard-coding a hostname or authorization URL:

  • /.well-known/oauth-authorization-server
  • /.well-known/oauth-protected-resource
  • /.well-known/jwks.json
  • /openapi.json

The public OpenAPI contract covers the credentialless action control plane. It does not grant access and it does not document internal dashboard, cron, or general secret-delivery routes as AI-agent interfaces.

The contract is OpenAPI 3.1.1. Its stable REST objects are closed schemas, examples are validated during CI, and only provider-defined action arguments and JSON-RPC extension data remain intentionally dynamic.

Public Codex plugin submission

The public Codex/ChatGPT plugin path uses the canonical HTTPS MCP URL https://runenv.dev/api/mcp/agent-guard and RunEnv OAuth discovery. A developer-mode plugin_asdk_app_… connection is useful for sandbox testing, but it is not a public marketplace submission identifier. Public submission uses the current OpenAI app-submission workflow for Plugin Directory distribution, any requested domain-verification proof at /.well-known/openai-apps-challenge, the seven tool annotations, and the review packet maintained with the RunEnv plugin source.

For help with a marketplace connection, use the RunEnv technical-support contact form. RunEnv does not claim workspace-domain restrictions for this integration until it adds the corresponding OIDC UserInfo capability.

Grok Build and Grok Chat

Grok Build and Grok Chat are separate integrations. A Grok Build plugin is not a Grok Chat connector, and neither integration accepts a pasted RunEnv token, service token, connector credential, or manually chosen project ID.

Grok Chat uses a remote Streamable HTTP MCP connector. It is not yet generally available: its public release remains gated on the non-production host matrix, live provider sign-off, design-partner decision, and publisher review. Do not configure it against a production project until RunEnv announces availability.

For a RunEnv-approved controlled non-production exercise, a release owner uses Grok connectors to create a Custom MCP connector with the exact reviewed canonical URL:

https://<configured-runenv-origin>/api/mcp/agent-guard

Grok then discovers the matching OAuth and protected-resource metadata, opens the RunEnv browser sign-in, and the human sponsor selects a scoped project inside RunEnv. Do not configure a static Authorization header, an arbitrary endpoint from a prompt or repository, or a project identifier in the connector URL.

For self-hosted production use, the configured origin must be a publicly reachable canonical HTTPS issuer with matching OAuth metadata. A temporary tunnel can be used only for a controlled developer test of a disposable non-production instance; it is never a supported public endpoint, launch evidence, or a substitute for the required host/provider exercises. The connector sends Content-Type: application/json, accepts both application/json and text/event-stream, and sends one JSON-RPC message per POST; RunEnv rejects batch requests.

Agent-readable documentation

Start with /llms.txt, which is the bounded documentation index. Use /llms-full.txt only for offline indexing, vectorization, or a context window large enough for the complete public corpus. The strict discovery manifest and its JSON Schema are available at:

  • /.well-known/runenv-docs.json
  • /.well-known/runenv-docs.schema.json

Every public documentation page has a generated Markdown equivalent. Append /index.md to a localized documentation URL or send Accept: text/markdown to the normal page URL. The HTML page also includes View as Markdown and Copy as Markdown controls. Markdown responses include X-Markdown-Tokens, a deterministic estimate for context-window planning, and Vary: Accept when content negotiation is used.

RunEnv publishes Content-Signal: search=yes, ai-input=yes, ai-train=no by default. This permits search and runtime grounding while reserving documentation from model training. An operator may explicitly opt in to training only after a content-policy review.

Delegation and revocation

Delegated agents are attenuation-only. A child may request fewer OAuth scopes and narrower connector, action, resource-type, and resource-ID patterns, but it cannot widen any parent boundary. Delegation depth is capped at three, and a child expires no later than its parent.

The creation response contains one short-lived bearer token. Treat that response as sensitive even though it is marked Cache-Control: no-store: never log, persist, or put the token in a prompt. Revoking or expiring any grant in a delegation chain invalidates descendant access on the next request.

Exposure report publication

runenv agent doctor . keeps actionable relative paths local. Explicit publication uses a separate strict wire contract: finding paths are keyed hashes, skipped-file paths are omitted, and credential fingerprints and values are never transmitted. The server stores aggregate counts only.

Action lifecycle

  1. Discover the connector actions that are available to the authenticated project identity.
  2. Preview one returned connector and action with bounded arguments and a reason. RunEnv derives the exact resource; a supplied resource can only assert that same target.
  3. Request a permit bound to that preview.
  4. Wait for human approval when policy requires it.
  5. Execute the one-use permit with an idempotency key.
  6. Read the redacted status and receipt. Cancel or roll back only through the bound action workflow.

RunEnv verifies policy, scope, project binding, risk, permit expiry, approval state, connector configuration version, and connector status before queuing an external action. A changed policy revision or connector configuration invalidates stale previews and permits. A rollback creates a fresh preview and permit; elevated-risk rollbacks wait for independent approval instead of executing immediately.

Safety rules for agents

  • Never place a RunEnv token, OAuth authorization code, refresh token, connector credential, or secret value in an agent prompt, source file, chat transcript, action argument, or MCP configuration.
  • Do not use a service token as a shortcut for Agent Guard. Service-token and MCP-token boundaries are intentionally route-scoped.
  • Treat a permit that awaits approval as pending work, not a successful action.
  • Keep action reasons specific and non-sensitive. Do not put credentials, customer data, or secrets in a reason.
  • Use the narrowest project and OAuth scopes possible. Revoke a delegation or disable a client when it is no longer needed.

Troubleshooting

The connection preview is correct but nothing changed

runenv agent connect is preview-only until you add --yes. Re-run the same command with --yes, then complete browser authorization.

Authorization fails or the client cannot discover tools

Confirm that the project ID is correct, the human sponsor can access the project, and the OAuth resource and issuer belong to the configured RunEnv server. Reconnect the client if its stored profile is missing or expired.

A permit is waiting for approval

This is expected for policy-gated work. Ask an authorized reviewer to approve or reject the exact preview. Do not create a substitute action to bypass review.

An action was denied or cancelled

Read the redacted status and receipt metadata. Check the configured connector, allowed action, policy revision, project scope, and permit expiry before creating a new preview.