Environment Variables - Theo API Docs

Variables

Variable	Required	Default	Used By	Description
`THEO_API_KEY`	✅	—	CLI, SDK, MCP	Your `theo_sk_...` API key
`THEO_BASE_URL`	—	`https://www.hitheo.ai`	CLI, SDK, MCP	Override API base URL
`THEO_ALLOW_JS_CONFIG`	—	unset	MCP	When `1`, allows the MCP server to load `theo.config.js` / `theo.config.ts` instead of `theo.config.json`. Off by default for safety — JS/TS config executes arbitrary code from the working directory.

THEO_BASE_URL defaults to the canonical www host. Pointing it at https://hitheo.ai (without www) causes the apex to 307-redirect to www, which some HTTP clients handle by stripping the Authorization header — first-time 401. See 401 Troubleshooting.

Where They’re Used

CLI — theo complete, theo status, theo verify, theo skill publish all read THEO_API_KEY. theo status also probes both apex and www regardless of which one THEO_BASE_URL points at, so a misconfigured env var is surfaced as a warning.
MCP Server — The @hitheo/mcp server reads THEO_API_KEY on startup and injects it into every tool call. THEO_BASE_URL defaults to https://www.hitheo.ai as of @hitheo/mcp@0.2.0.
SDK — For programmatic use, pass the key directly:

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

Setting Variables

export THEO_API_KEY=theo_sk_live_a1b2c3d4e5f6...

THEO_API_KEY=theo_sk_live_a1b2c3d4e5f6...
THEO_BASE_URL=https://www.hitheo.ai

Precedence

Explicit constructor parameter (SDK) or CLI flag
Environment variable
.env file in the current directory Explicit values always override environment variables.

​Variables

​Where They’re Used

​Setting Variables

​Precedence

Variables

Where They’re Used

Setting Variables

Precedence