Client Setups
Step-by-step setup for popular IDEs and tools.
#Claude Code
Anthropic CLI tool with custom base URL support.
- 1Set environment variables before launching; ANTHROPIC_BASE_URL must end with /claude/.
- 2ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY should both contain your JWT token.
- 3Pin the Opus/Sonnet/Haiku and subagent tiers to mapped model names.
export ANTHROPIC_BASE_URL=https://<gateway-host>/claude/
export ANTHROPIC_AUTH_TOKEN=<token>
export ANTHROPIC_API_KEY=<token>
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
export ANTHROPIC_DEFAULT_OPUS_MODEL=<mapped-model>
export ANTHROPIC_DEFAULT_SONNET_MODEL=<mapped-model>
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<mapped-model>
export CLAUDE_CODE_SUBAGENT_MODEL=<mapped-model>
claude#Claude Desktop
Claude Desktop in third-party inference mode — routes chat through Portway as an Anthropic-compatible gateway.
- 1Developer Mode: Help → Troubleshooting → Enable Developer Mode.
- 2Developer → Configure third-party inference; provider = Gateway.
- 3Under Custom inference headers add X-Maestro-Client: claude-desktop (required).
- 4Pick models from discovery using the opaque id (claude-maestro-…).
Gateway base URL: https://<gateway-host>/claude
Gateway API key: <token> (auth scheme: bearer)
inferenceCustomHeaders:
{ "X-Maestro-Client": "claude-desktop" }#OpenClaw
Universal AI IDE plugin reading provider config from ~/.openclaw/openclaw.json.
{
"models": {
"mode": "merge",
"providers": {
"portway": {
"baseUrl": "https://<gateway-host>/openclaw",
"apiKey": "<token>",
"api": "openai-completions",
"models": [{ "id": "<mapped-model>", "name": "<mapped-model>" }]
}
}
}
}#Codex (OpenAI)
Via the Desktop App launcher script (recommended) or the VS Code extension / CLI with env vars.
# Desktop App — recommended (do NOT put /v1 in MAESTRO_URL)
MAESTRO_URL=https://<gateway-host> MAESTRO_TOKEN=<token> \
MAESTRO_MODEL=<mapped-model> ./scripts/codex-maestro
# VS Code Extension / CLI
export OPENAI_BASE_URL="https://<gateway-host>/v1"
export OPENAI_API_KEY="<token>"
codex#Cursor IDE
Editor using a custom OpenAI base URL. Also supports the Cursor AI provider node directly.
- 1Cursor Pro is required for custom API keys; Portway must be publicly reachable (VPS/tunnel).
- 2Settings → Models → OpenAI → Override Base URL.
OpenAI API Key: <token>
Override OpenAI Base URL: https://<gateway-host>/cursor#Grafana Assistant
Official Grafana plugin for AI-powered dashboards (Grafana ≥ 13.0.0).
Backend URL: https://<gateway-host>/grafana/assistant
API Token: <token>#VS Code
Claude Code, Codex and Kilo Code extensions are supported. Most work via env vars or the /v1 base URL.
{
"terminal.integrated.env.osx": {
"OPENAI_BASE_URL": "https://<gateway-host>/v1",
"OPENAI_API_KEY": "<token>"
}
}#Open WebUI
The chat UI bundled with Portway; open it from the Open WebUI link in the sidebar. It runs under /webui/ on the same address as the panel, with no extra port or domain.
- 1Open WebUI talks to Maestro over /v1 with the openwebui service user's token.
- 2Each request forwards the signed-in user's email in the trusted-client header (X-OpenWebUI-User-Email); Portway attributes it to the user with that email.
- 3Create a Portway user with the same email for every Open WebUI user; without a match the request gets 403.
- 4make openwebui syncs the service user, its token and the Open WebUI connection settings (make setup runs it for you).
make openwebui