Network configuration

Theus is local-first: it runs offline against a local index and only reaches the network when you point it at a model provider. This page covers how to route model traffic through a custom base URL or proxy, how the local project API on loopback behaves, and how to run Theus with no outbound connections at all.

Local-first by design

Theus never makes a remote service mandatory to start. On launch it selects a model provider in a fixed order (see Providers) and, if none is configured, it degrades to the built-in compat engine. Independently of the model, the project intelligence service indexes your code and serves a dashboard entirely on 127.0.0.1. Both subsystems can be disabled, so you can run Theus with zero network egress.

Routing model traffic (base URL / proxy)

The main provider resolver in services/api/theus.ts reads a base URL directly from the environment. Setting either variable makes Theus send all model requests to that endpoint, which is also how you place a reverse proxy or gateway in front of your provider.

Point Theus at a local proxy or self-hosted gateway:

export THEUS_BASE_URL="http://127.0.0.1:8080/v1"
export THEUS_API_KEY="sk-your-key"
export THEUS_MODEL="gpt-4o"
./bin/theus

Fallback chain

At call time Theus builds a fallback chain: the routed provider, then the default env/policy provider, then the remaining enabled OpenAI-compatible providers from ~/.theus/providers.json, deduplicated by {id, baseURL, model}. If one fails on a network or HTTP error, the next is tried, and the compat engine is the last resort. With THEUS_DISABLE_MAIN_PROVIDER active, config providers are not enumerated at all.

The local project API

The project intelligence service (services/projectIntelligence/) starts an HTTP server bound exclusively to 127.0.0.1. It indexes your project, exposes a graph and detected database schema, and serves a neural-map dashboard. It never listens on a public interface.

Binding and port

The server always calls listen(port, '127.0.0.1'). By default it picks a free ephemeral port; set a fixed one with an environment variable:

export THEUS_PROJECT_API_PORT=8790
THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus

The resolved URL is http://127.0.0.1:<port>. You can read it from the CLI's status output, and the endpoints below answer there.

Endpoints

curl http://127.0.0.1:8790/api/health
curl "http://127.0.0.1:8790/api/status?token=$THEUS_PROJECT_API_TOKEN"

Loopback and token security

Every request must satisfy three checks, so the local API stays private to your machine:

• Loopback host only. The Host header must resolve to 127.0.0.1, localhost, or ::1; anything else is rejected with 403 forbidden_host. This blocks DNS-rebinding attacks from a malicious web page.
• Origin allowlist. A browser Origin that is not loopback gets 403 forbidden_origin.
• Session token. Every path except /api/health requires the session token. It is generated at startup (or fixed with THEUS_PROJECT_API_TOKEN). Send it as the ?token= query param, the x-theus-token header, or Authorization: Bearer. A missing or wrong token returns 401 unauthorized.

The dashboard receives the token via a query parameter on its URL and forwards it on its own fetch() calls, so opening it from the CLI works with no extra setup.

Running fully offline

To keep Theus from making any outbound connection, disable the model provider and the local services:

# No model egress — force the built-in compat engine
export THEUS_DISABLE_MAIN_PROVIDER=1

# No indexing, no local API, no dashboard
export THEUS_NO_PROJECT_INTELLIGENCE=1

./bin/theus

Related

• Providers — configuring ~/.theus/providers.json and the resolution order.
• Security — the local API's threat model in depth.