Guides

Run AgenticOS on Stav

Add Stav as a model in a self-hosted AgenticOS, choose EU, EEA or global per model, and run its agents through Stav.

AgenticOS is an open-source platform for building and running AI agents on your own servers. Its agents chat, call tools, run code and search knowledge bases. Since version 1.41.0, Stav.ai is one of its model providers, with a region on each model.

Point it at Stav and every agent turn is billed to your Stav credits, shows up in your request log, and follows your workspace policy. Choose EU only on a model and its requests run on EU compute, or are refused.

Tested with AgenticOS 1.43.0 against the Stav API, installed with its quickstart script in Docker. Earlier versions are covered under AgenticOS before 1.41.

Before you start

A Stav API key. See Authentication. Give it the scope inference:chat, and inference:models so AgenticOS can list the models.
AgenticOS 1.41.0 or later. See its quickstart. You can start it with --provider none and add Stav afterwards.

Running AgenticOS on a server, not on localhost

When people reach AgenticOS by a host name, set PUBLIC_API_URL, PUBLIC_WS_URL, PUBLIC_SITE_URL, FRONTEND_URL and CORS_ORIGINS in its .env. Run the quickstart first, then add these and run docker compose up -d. The quickstart writes SECRET_KEY and VAULT_MASTER_KEY only when it creates .env itself. If the file is already there, it starts the stack without them, and the vault cannot open the keys it stores.

If that already happened, add both keys, then reinstall on an empty database. A key saved without them cannot be read with them:

cd ~/agenticos   # the folder with docker-compose.yml and .env
printf 'SECRET_KEY=%s\nVAULT_MASTER_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" >> .env
docker compose down -v   # deletes the AgenticOS data
curl -fsSL https://raw.githubusercontent.com/vstorm-co/agenticos/main/scripts/quickstart.sh | bash -s -- --yes --provider none --dir .
docker compose exec app agenticos cmd doctor   # should end "Everything this can check is working."

Set it up

In AgenticOS a model is a model profile: a provider, a model id, a key from the vault and, for Stav, a region. Open an agent, go to its model, and choose Add model. Fill in:

Field	Value
Provider	`Stav.ai`
Key	Your Stav key, `sk_stav_live_...`, saved in the vault for Stav.ai
Model	Pick one from the list, e.g. `deepseek-ai/deepseek-v4-flash-0731`
Region	`EU only` (the default), `EEA only` or `Global`
Endpoint	Leave empty

The model list comes from Stav. AgenticOS reads it from https://api.stav.ai/v1/models with a Stav key from your vault.
There is no API to choose. Stav says which API serves each model. AgenticOS uses Chat Completions where the model has it, and the Responses API for the few models served only there, such as openai/o3-pro. The form shows which one it picked.
Leave Endpoint empty. It is only for a regional or test endpoint of Stav.

The same profile through the AgenticOS API:

curl -X POST http://localhost:8000/api/v1/providers/model-profiles \
  -H "Authorization: Bearer $AGENTICOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Stav DeepSeek V4 Flash (EU)",
    "provider": "stav",
    "model": "deepseek-ai/deepseek-v4-flash-0731",
    "secret_id": "<vault secret id of your Stav key>",
    "region": "eu"
  }'

Then publish the agent and send it a message.

Choose where requests run: EU, EEA or global

The region on the profile goes to Stav as the X-Stav-Runs-In header on every request. Stav then answers only from Provider Endpoints that compute there, fails over only inside it, and refuses a request it cannot serve there. Global sends no header, so only your workspace policy applies. A region can only narrow your workspace policy, never widen it.

EU only is the default. A profile saved without a region runs in the EU.
The profile's settings cannot change it. AgenticOS sets the header on each request itself, so an extra_headers or extra_body in the profile's params does not move an EU or EEA profile out of its region.
The model list is not filtered by region. It shows every model your key can reach. If a model has no Provider Endpoint in the region, a run fails with HTTP 403 (see Troubleshooting). To see which models run in the EU, filter the model catalogue on compute region.

Make one profile per region you want to offer, for example Stav auto (EU) and Stav auto (global), and pick between them per agent. The request log shows the region on each request, and says it came from the header. See Choose where a request runs.

Use the Anthropic API instead

AgenticOS can also talk to Stav over the Anthropic Messages API. Stav translates it for every model, not only Claude. This profile has no Region field, so set Compute region in your workspace policy if it must stay in the EU (see Pick a model).

Field	Value
Provider	`Anthropic`
Model	A Stav model id, e.g. `deepseek-ai/deepseek-v4-flash-0731`
Key	Your Stav key, saved in the vault for Anthropic
Endpoint	`https://api.stav.ai`, without `/v1`

The Anthropic SDK adds /v1/messages itself. Give the key the scope inference:messages too.

One key, one vault entry per provider

A vault key in AgenticOS belongs to one provider. To use Stav through both the Stav.ai and the Anthropic provider, save the same Stav key twice: once for Stav.ai, once for Anthropic.

Pick a model

You send	What happens
`creator/model`, e.g. `deepseek-ai/deepseek-v4-flash-0731`	Stav picks one of the model's Provider Endpoints in the profile's region
`creator/model/provider`	One Provider Endpoint. Use this to know where the work runs
`auto`	Your default Router picks a model per request, inside the profile's region
`@your-workspace/router`	A named Router you set up in Your workspace → Connect → Routers
`anthropic/…`, `openai/…`	Works on a Global profile. Stav forwards the request to that US provider, so your policy and request log apply. On an EU or EEA profile, only those with a Provider Endpoint in the region answer

On a Global profile, auto can pick a Claude or GPT model. In our test it chose anthropic/claude-sonnet-5-5 for an agent turn with tools.

To keep everything in the EU for every app, set Compute region to EU only in Your workspace → Govern → Key policies → Reach. That applies to every request from every key, including auto, models you name, and profiles saved as Global. See Enforce a sovereignty floor.

Knowledge bases

AgenticOS cannot send knowledge-base embeddings to Stav yet. Its embedding settings take a custom endpoint for one hosted provider only, and Stav is not on its list. Embed knowledge bases with one of the embedding providers AgenticOS lists. If your documents must stay in the EU, use its Ollama provider on your own network.

Agents that search a knowledge base still answer through Stav.

What works

Feature	Status
Chat, streaming	Works
Tool calls (`run_python` and other tools), streaming and not	Works
Region per model (EU, EEA, global)	Works. A model outside the region is refused
Model list from Stav	Works
Responses-only models, e.g. `openai/o3-pro`	Works, on a Global profile
Reasoning output (the "Thought for" line)	Works on models that return it
Anthropic Messages API, streaming and tools	Works, on non-Claude models too
`auto`	Works
Knowledge-base embeddings	Not through Stav yet. See Knowledge bases
Cost shown in AgenticOS	Shows 0 and marks it partial. The real cost is in your Stav request log

Image generation, speech, web research and the other capabilities that have their own provider settings were not tested with Stav.

Spend

AgenticOS does not know Stav's prices, so it shows each run as costing 0. Its own agent budgets cannot see what you spend. Set a spend cap on the Stav key instead, in Your workspace → Connect → API keys. The cap holds on every request the key makes.

Each agent turn also sends AgenticOS's own instructions and tool definitions before your message. In AgenticOS 1.43.0 that was about 57,000 input tokens for a one-line question on the default agent (about 2,000 in 1.31.3). On an expensive model this is most of the cost: one "Reply with exactly: pong" turn on openai/o3-pro cost about €0.75. Give agents only the capabilities they need, and pick a model with a low input price.

AgenticOS before 1.41

Older versions have no Stav.ai provider. Use the OpenAI provider with the endpoint https://api.stav.ai/v1 (keep /v1), type the model id, and leave API on Chat Completions. There is no region field: set it through the AgenticOS API as "params": {"extra_headers": {"X-Stav-Runs-In": "eu"}} on the profile. params is replaced as a whole when it is changed, so include the header again on every edit, or upgrade to 1.41 or later.

Troubleshooting

You see	Do this
`ModelAuthenticationError, HTTP 403` on a run	Usually not the key: the model has no Provider Endpoint in the profile's region, so Stav refused it. Pick a model that runs there, or a wider region. Your Stav request log shows the refusal and why
`ModelHTTPError, HTTP 401` on a run	Check the Stav key in the vault entry the model profile uses
`Choose a vault key before listing this endpoint`	You set an Endpoint. Choose the key first, or leave Endpoint empty
`404` on every request, Anthropic provider	The endpoint must not end in `/v1`
`agenticos cmd doctor`: `VAULT_MASTER_KEY is unset` or `credential could not be unsealed`	`.env` existed before the quickstart ran. See Running AgenticOS on a server
A request ran outside the EU	Check that the profile's Region is `EU only`, or set Compute region in Your workspace → Govern → Key policies → Reach

More error codes: Errors.

Check it worked

Open Your workspace → Monitor → Request log. Each model call is one row, with the model, Inference Provider, country and cost. An agent turn with a tool is two rows: the tool call and the answer. See Request log and prompt capture.