Xilos is live — connect your agents today →
Getting Started
Connect Your First Agent

Connect Your Agent

Xilos exposes an OpenAI-compatible API endpoint, so any framework that lets you override the base URL can connect to Xilos without code changes. The pattern is the same for every integration:

  1. Set the base URL to https://api.xilos.ai/api/v1.
  2. Set the API key to your Xilos API key (or a Virtual Key with scoped limits).
  3. Send requests to the /chat/completions endpoint as you normally would.

Info: Xilos is a drop-in replacement for the OpenAI Chat Completions API. Every request is automatically processed through your routing rules, restriction rules, guardrails, and caching layer — no application code changes required.

Prerequisites

Before you connect an agent, make sure you have:

  • A Xilos account with an active organization.
  • An API key from Settings in the Xilos dashboard, or a Virtual Key with appropriate scopes and limits.
  • The base URL: https://api.xilos.ai/api/v1.

Choose Your Framework

Hermes

Hermes Agent (opens in a new tab) is an AI agent runtime by Nous Research. To route Hermes traffic through Xilos, set the provider base URL and API key in your Hermes configuration.

Open your Hermes config

Edit the provider configuration in your Hermes profile (typically ~/.hermes/config.yaml or the profile-specific YAML).

Set the base URL and API key

providers:
  xilos:
    base_url: https://api.xilos.ai/api/v1
    api_key: ${XILOS_API_KEY}
    # Model name sent to Xilos; Xilos routes to the actual LLM
    model: xilos

Export your API key as an environment variable

export XILOS_API_KEY="your-xilos-api-key"

Set Xilos as the active provider

model:
  provider: xilos
  name: xilos

Verify the connection

Run any Hermes command that triggers an LLM call. Open the Xilos dashboard Query Log to confirm the request was processed through Xilos.

OpenClaw

OpenClaw (opens in a new tab) is an open-source agent framework. Configure it to use Xilos as the OpenAI-compatible backend.

Set environment variables

export OPENAI_API_KEY="your-xilos-api-key"
export OPENAI_BASE_URL="https://api.xilos.ai/api/v1"

Configure the model in your OpenClaw config

model:
  name: xilos
  provider: openai

Run your agent

openclaw run

All LLM calls are now routed through Xilos.

Claude Code

Claude Code (opens in a new tab) is Anthropic's CLI coding agent. Connect it to Xilos by overriding the API base URL.

Set environment variables

Claude Code respects the standard ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY variables. Because Xilos is OpenAI-compatible, use the OpenAI-compatible override instead:

export OPENAI_API_KEY="your-xilos-api-key"
export OPENAI_BASE_URL="https://api.xilos.ai/api/v1"

Launch Claude Code with the OpenAI provider

claude-code --provider openai --model xilos

Verify in the dashboard

Check the Query Log in your Xilos dashboard to confirm Claude Code traffic is flowing through Xilos.

Warning: If your version of Claude Code does not support OpenAI-compatible providers, check the latest Claude Code documentation for the current override mechanism. The principle remains the same: point the base URL at https://api.xilos.ai/api/v1 and use your Xilos API key.

OpenAI SDK

The official OpenAI SDKs for Python and JavaScript work with Xilos out of the box — only the base_url and api_key change.

Python

    from openai import OpenAI
 
    client = OpenAI(
        api_key="your-xilos-api-key",
        base_url="https://api.xilos.ai/api/v1"
    )
 
    response = client.chat.completions.create(
        model="xilos",
        messages=[
            {"role": "user", "content": "Hello, Xilos!"}
        ]
    )
 
    print(response.choices[0].message.content)

JavaScript

    import OpenAI from "openai";
 
    const client = new OpenAI({
      apiKey: "your-xilos-api-key",
      baseURL: "https://api.xilos.ai/api/v1",
    });
 
    const response = await client.chat.completions.create({
      model: "xilos",
      messages: [{ role: "user", content: "Hello, Xilos!" }],
    });
 
    console.log(response.choices[0].message.content);

TypeScript

    import OpenAI from "openai";
 
    const client = new OpenAI({
      apiKey: process.env.XILOS_API_KEY,
      baseURL: "https://api.xilos.ai/api/v1",
    });
 
    const response = await client.chat.completions.create({
      model: "xilos",
      messages: [{ role: "user" as const, content: "Hello, Xilos!" }],
    });
 
    console.log(response.choices[0]?.message?.content);

LangChain

LangChain (opens in a new tab) supports custom base URLs through the ChatOpenAI class. Point it at Xilos to route all chain and agent calls through your Xilos gateway.

Python

    from langchain_openai import ChatOpenAI
 
    llm = ChatOpenAI(
        model="xilos",
        api_key="your-xilos-api-key",
        base_url="https://api.xilos.ai/api/v1",
    )
 
    response = llm.invoke("Hello, Xilos!")
    print(response.content)

JavaScript

    import { ChatOpenAI } from "@langchain/openai";
 
    const llm = new ChatOpenAI({
      model: "xilos",
      apiKey: "your-xilos-api-key",
      configuration: {
        baseURL: "https://api.xilos.ai/api/v1",
      },
    });
 
    const response = await llm.invoke("Hello, Xilos!");
    console.log(response.content);

Info: When using LangChain agents or chains, the model value xilos lets your routing rules decide which underlying LLM handles the request. You can also pass a specific model name (for example, claude-sonnet-4) if you want to bypass routing.

OpenWebUI

OpenWebUI (opens in a new tab) is a self-hosted chat interface. Add Xilos as a custom OpenAI-compatible connection.

Open OpenWebUI settings

Navigate to Settings → Connections in the OpenWebUI admin panel.

Add a new OpenAI API connection

  • URL: https://api.xilos.ai/api/v1
  • API Key: your-xilos-api-key

Save and enable the connection

Click Save and toggle the connection to enabled. OpenWebUI will fetch the model list from Xilos.

Select the Xilos model

In the chat interface, select the xilos model (or any model surfaced by your routing configuration). Messages now flow through Xilos.

Verify the Connection

Regardless of which framework you connected, verify that traffic is flowing through Xilos:

Send a test message

Trigger any LLM call from your agent or application.

Open the Xilos dashboard

Navigate to the Query Log in the sidebar.

Confirm the query appears

You should see the query, the routing decision, any governance actions applied, and the cost breakdown.

Next Steps

QuickstartCore Concepts