AgentsClients

Guardrail Clients

Beta feature. Policy syntax and behavior may change as OpenAPPA evolves.

Guardrails check the tool calls of any client that sends its traffic through the Archestra LLM Proxy. Built-in clients work out of the box. Any other client needs to add the X-Appa-Session-ID and X-Appa-Parent-ID headers.

Connect a Supported Client

These clients work without extra configuration:

  • Archestra Chat
  • Claude Code
  • Claude Desktop (Code and Cowork tabs)
  • Codex CLI
  • ChatGPT desktop app (Work and Codex tabs, see ChatGPT)
  • Copilot CLI (see Copilot CLI for the providers it works with)
  • Pi
  • OpenCode
  • Kilo Code
  • Kimi Code
  • Grok Build CLI

Connect the client to the LLM Proxy and the MCP Gateway on the connection page. The client needs both: the LLM Proxy checks each tool call, and the MCP Gateway gives the agent the tools to handle a block, such as get_remedy_plans and yell.

Use Guardrails in Kimi Code

Kimi Code shows a review in its own question form: choose Inspect, Allow, or Deny. Inspect shows the complete review, and you then choose Allow or Deny. Escape closes the form without approving or denying.

  • Subagents run under Guardrails only as new foreground Agent calls. A background, resumed, or swarm subagent is refused before it starts.
  • Setup starts Kimi Code in Ask When Needed mode, so the guardrail helpers run without a prompt. Kimi Code 2.3.3 cannot approve single gateway tools, so this mode also runs your other gateway calls and routine commands without asking. It still asks before dangerous commands and shows reviews.

Grok Native Tools

Choose Grok Build on the connection page, complete setup, and start grok in a new terminal. Subscription mode retains native model names, reasoning options and /model selection while routing inference through Archestra. This setup configures the CLI, not Grok Bot desktop.

Interactive startup shows configuration, skill sync, model discovery and proxy routing progress on stderr. Routing remains pending server admission; startup is not proof that a session is protected. The first eligible governed reply displays the server-issued protected session receipt, as it does for other native clients. This is a reply indicator, not a persistent Grok status-bar badge. Headless prompts skip the screen and check connectivity in the background. Plain output reports status on stdout; JSON output retains native reply fields and adds _meta.archestraStartup to the final object. Other quiet and non-terminal runs keep native stdout unchanged. Guardrails checks run in the proxy, never in client hooks.

PowerShell, Bash and Zsh profiles also route Grok's own agent command through this launcher. On Unix, both names must resolve to the same executable. An unrelated agent command, alias or function keeps its existing behavior. Open a new terminal after connecting to load the managed functions.

On Unix, the managed function replaces any existing grok alias in the loaded shell. Its original declaration stays in your profile and takes effect again in a new terminal after disconnecting.

The launcher uses a dedicated profile for native skills and managed hook isolation. Grok reads and refreshes the ordinary native login directly; /login and node ~/.archestra/grok/login.cjs renew that same login. Credentials are never copied, and conflicting native routing policies stop launch.

Grok's paired provider-hosted web and X search capability is unavailable on this connection. The protected catalog does not advertise it; unsupported tool declarations remain blocked.

Grok's Opt out and Opt in controls update your xAI coding-data-sharing preference. Changes are audited; a rejected update leaves Grok's cached preference unchanged.

The proxy reads Grok's native session header and checks tool calls before returning them for execution. Shell commands, file reads, edits, writes and searches use the coding-tool policy. The starter policy includes the target_file argument binding for Grok reads; existing custom policies are not changed. Other recognized tools still go through policy evaluation. Unknown native tools are refused.

Subagents inherit their parent's labels and return only through a declared return contract. Foreground results, completed background results and native completion notifications pass through the same return checks. Partial, failed and cancelled task output is withheld. Reading raw native session files is refused.

Resuming a completed protected child retains its labels and original return contract, even though Grok assigns it another native ID. Only a verified child of the current parent can be resumed. Workflows, monitors and scheduled execution remain unavailable.

Managed Grok sessions support native direct messages from a parent to its child and between eligible siblings. Guardrails checks the sender, recipient and message before the recipient model reads it. Messages that require different labels stay held until the recipient completes the offered remedy. Delivery acceptance is separate from the child’s checked return. Nested spawning and child-to-root messaging remain unavailable in Grok.

Grok discovers MCP tools through search_tool and calls them with use_tool. The proxy checks the dispatched target and its arguments, not just the wrapper. Unsigned targets cannot acquire platform remedy authority from their names. Nested dispatchers are refused. The MCP Gateway independently checks the actual call in the same session. Gateway tool names use a Grok-compatible spelling; policy identities and permissions stay unchanged. Interactive Grok sessions can show native approval questions. Headless or unanswered questions never approve a call.

The proxy verifies gateway signatures preserved in Grok's search_tool results before treating a deferred tool as a platform tool. It checks the exact target and arguments inside use_tool, then returns allowed calls and remedy notices in that same format. A target string alone grants no platform authority. If discovery results are missing after compaction, rediscover the gateway tools before requesting a remedy. Native approval answers bind to the issued question and session; JSON or unrecognized answers do not approve a call.

The protocol was checked with Grok Build 1.0.70, including native login, model selection, resume, skill discovery and synthetic policy reviews. Synthetic upstream checks do not verify paid subscription inference. Directly launching the underlying executable bypasses this connection.

Review Calls in OpenCode and Kilo Code

The connection plugin shows a command preview and the scope of an approval before you choose Allow or Deny. Choose Inspect for the exact arguments and full policy review. Dismiss or Escape closes the question without approving or denying.

Reconnect through the connection page and restart the client to install the question dialog. This requires a managed connection over HTTPS.

SurfaceQuestion Display
OpenCode CLI 1.19.3 and compatible later 1.x releasesCompact dialog with pages for long previews and full reviews.
Kilo Code CLI 7.8.15 and compatible later 7.x releasesThe same dialog using Kilo's native controls.
Older versions, OpenCode 2, or an unavailable TUI extensionThe client's native question UI.
Editor webviews, including Kilo's VS Code chatNative question UI. Running a supported CLI in an editor terminal uses the CLI dialog.
  • Inspect requires a separate answer afterward. Reading or paging through the review never selects Allow.
  • Multi-question and multi-select forms, small terminals, and forms with many or long option labels use the native UI.
  • An existing tui.jsonc is preserved without automatic registration. The native question remains available.

ChatGPT

Guardrails follow the desktop app's Work and Codex tabs. Both run on your computer and read the Codex settings there. On Connect, select ChatGPT and run its terminal setup command to route model requests through the LLM Proxy. See Use Guardrails in the Desktop App.

  • Not covered: chats and dots run on OpenAI's servers, so their tool calls never reach the proxy.
  • Approvals: a review shows as a form from the MCP gateway in the task, as in Codex CLI.

Copilot CLI

Guardrails follow a Copilot CLI session when its model requests use the OpenAI Responses API. Copilot names its conversation only there. Setup selects that API when the proxy serves it for your provider: OpenAI, Azure, GitHub Copilot, or xAI. On other providers Copilot keeps the Chat Completions API, and the proxy treats it as an unrecognized client.

  • Reconnect to turn it on: a Copilot CLI connected before this support stays on the Chat Completions API. Connect it again from the connection page.
  • Subagents: Guardrails follow a subagent that the task tool starts. Signed in to GitHub, Copilot would otherwise run a subagent on its own default model, whose requests go to GitHub directly, so the proxy runs it on your session's model instead. A task call that names a model outside your Archestra provider is refused, with the models you can use. A background subagent's result reaches your session when Copilot reads it with read_agent, also after you send a new prompt while the subagent runs. Subagents from fleet mode or dynamic workflows have no governed parent, and the proxy refuses their model requests.
  • Approvals: a review shows as Copilot's own question in an interactive session. Copilot loads most MCP tools only when the model searches for them, so the proxy loads the remedy, question, and report tools up front. Copilot's MCP client declines the gateway's form, so a one-shot (-p) session cannot answer a review. Setup lets Copilot run the guardrail helpers, such as get_remedy_plans, without asking each time.

Configure Other Clients

Any other client, such as n8n or your own app built with an SDK, sends the session headers with every model call. Guardrails use them to remember restrictions across turns, tool calls, and retries.

  • X-Appa-Session-ID: your app's conversation ID or workflow run ID. If you do not have one, generate a UUID when the conversation starts and reuse it.
  • X-Appa-Parent-ID: the parent's session ID, when a subagent or child workflow makes the call. Leave it out otherwise.
  • X-Archestra-Unattended: 1 when no person can answer approvals in the session, so the Break the glass settings can let a call that waits for human approval through. Leave it out otherwise.
bash
export SESSION_ID="$(uuidgen)"

curl "https://archestra.example.com/v1/openai/chat/completions" \
  -H "Authorization: Bearer $ARCHESTRA_VIRTUAL_KEY" \
  -H "X-Appa-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Reuse the same ID for the whole conversation, including when you send tool results back. Start a new ID only for a new conversation.

Protection Limits

Guardrails check tool calls that go through the LLM Proxy. They do not cover:

  • Other traffic: a client that skips the proxy, or sends no session header, is not checked. To refuse such clients, set Other clients to Blocked in Settings → Guardrails.
  • The machine itself: shell, files, and network are not sandboxed. Run the agent in Agent Runtime to isolate it.
  • Provider-hosted tools: a provider's own tools, such as its web search, run before the proxy sees them.
  • Code mode: the proxy sees only the script, not the tool calls it makes, so Guardrails do not check them. Codex sessions in code mode are refused. In OpenCode, set "codemode": false on the gateway's entry under mcp.servers so its tools are called directly.