You are viewing the docs for Archestra v1.4. View the latest docs
Guardrail Clients
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
- Codex CLI
- OpenCode
- Kilo Code
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_ and yell.
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:1when 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.
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.