Configuration & Access#

This page is not just an environment-variable list. It answers three practical questions:

1. which settings are the minimum for this deployment
2. how admins are supposed to get in
3. which token downstream clients should actually use

Start by choosing an access model#

Tavily Hikari has two different access layers:

• admin access: who may enter /admin and call admin endpoints such as /api/keys
• user / client access: who may call /mcp or /api/tavily/*

Recommended defaults:

• local development: DEV_OPEN_ADMIN=true
• self-hosted single instance: built-in admin login
• production gateway: ForwardAuth
• end-user sign-in: Linux DO OAuth only when needed

Core runtime settings#

No matter which access model you choose, these settings are the main runtime contract:

Notes:

• TAVILY_UPSTREAM has a default and usually does not need to be overridden in local development, but you should override it when using a mock, sandbox, or custom upstream.
• TAVILY_USAGE_BASE defaults to https://api.tavily.com and affects usage / quota sync flows.
• TAVILY_UPSTREAM is treated as the full MCP endpoint. If your reverse proxy preserves a path prefix, include the final /mcp path in the configured URL.
• TAVILY_USAGE_BASE may also include a path prefix. Hikari appends /search, /extract, /crawl, /map, /research, /research/{id}, and /usage under that prefix.
• WEB_STATIC_DIR is optional. If omitted, the app will try to use web/dist when that directory exists.
• TAVILY_API_KEYS is convenient for bootstrapping, but long-term key lifecycle should be managed through the admin UI or admin API.

Minimum config by deployment shape#

Local development#

This is the shortest path:

export DEV_OPEN_ADMIN=true
export PROXY_BIND=127.0.0.1
export PROXY_PORT=58087

That gives you:

• direct access to admin endpoints
• a quick path to inject the first upstream Tavily key
• local fallback behavior for /mcp and /api/tavily/* while validating the app

Use this only for local development.

Self-hosted single instance#

If there is no dedicated gateway, the simplest stable setup is the built-in admin login:

export ADMIN_AUTH_BUILTIN_ENABLED=true
export ADMIN_AUTH_BUILTIN_PASSWORD_HASH='<phc-string>'
export ADMIN_AUTH_FORWARD_ENABLED=false

This is the minimum reliable self-hosted setup. The admin signs in through the browser, receives an HttpOnly cookie session, and then uses /admin and the admin API from there.

Production gateway / zero-trust edge#

If you already have a trusted reverse proxy or identity gateway, use ForwardAuth:

export ADMIN_AUTH_FORWARD_ENABLED=true
export FORWARD_AUTH_HEADER=Remote-Email
export FORWARD_AUTH_ADMIN_VALUE=admin@example.com
export FORWARD_AUTH_NICKNAME_HEADER=Remote-Name

In that model, admin status is derived from the trusted identity header, not from a local cookie.

Admin access models#

ForwardAuth#

This is the recommended production model.

There are only three things that really matter:

1. which header identifies the caller: FORWARD_AUTH_HEADER
2. which value is treated as admin: FORWARD_AUTH_ADMIN_VALUE
3. whether the reverse proxy actually injects that value into the request

The most common misunderstanding is this:

• ADMIN_AUTH_FORWARD_ENABLED=true is the default
• but if FORWARD_AUTH_HEADER is not configured, that does not magically create admin access

In other words, “the switch is on” does not mean “ForwardAuth integration is complete”.

Built-in admin login#

The built-in admin login is a good fit for:

• self-hosted single-instance deployments
• internal deployments
• setups that do not yet have a dedicated ForwardAuth or SSO layer

Required rule:

• once ADMIN_AUTH_BUILTIN_ENABLED=true
• you must provide either ADMIN_AUTH_BUILTIN_PASSWORD or ADMIN_AUTH_BUILTIN_PASSWORD_HASH

Recommended rule:

• prefer ADMIN_AUTH_BUILTIN_PASSWORD_HASH
• avoid keeping ADMIN_AUTH_BUILTIN_PASSWORD around long-term

Generate a hash like this:

echo -n 'change-me' | cargo run --quiet --bin admin_password_hash

DEV_OPEN_ADMIN#

This is the development shortcut:

export DEV_OPEN_ADMIN=true

It does two things:

• opens admin access for local validation
• allows local fallback behavior for /mcp and /api/tavily/* when you are still wiring up the real auth path

Do not treat it as a production-grade access model.

Linux DO OAuth#

Linux DO OAuth is only for end-user sign-in. It is not an admin-auth mechanism.

Enable it when you want end users to log in through the web UI and automatically reuse their bound Hikari token:

export LINUXDO_OAUTH_ENABLED=true
export LINUXDO_OAUTH_CLIENT_ID='<client-id>'
export LINUXDO_OAUTH_CLIENT_SECRET='<client-secret>'
export LINUXDO_OAUTH_REDIRECT_URL='https://<your-host>/auth/linuxdo/callback'

Those three values are required together:

• LINUXDO_OAUTH_CLIENT_ID
• LINUXDO_OAUTH_CLIENT_SECRET
• LINUXDO_OAUTH_REDIRECT_URL

Other OAuth settings already have defaults and only matter when you need to override provider endpoints:

• LINUXDO_OAUTH_AUTHORIZE_URL
• LINUXDO_OAUTH_TOKEN_URL
• LINUXDO_OAUTH_USERINFO_URL
• LINUXDO_OAUTH_SCOPE

Session tuning is also available:

• USER_SESSION_MAX_AGE_SECS
• OAUTH_LOGIN_STATE_TTL_SECS

If Linux DO OAuth stays disabled, admins can still issue tokens manually for downstream clients.

Which token should clients use#

This distinction matters:

• admin endpoints use the admin access model, not Hikari tokens
• /api/tavily/* uses Hikari tokens
• /mcp also uses Hikari tokens

The Hikari token format is:

th-<id>-<secret>

That is the token you should hand to:

• Cherry Studio
• scripts
• custom backends
• MCP clients

Do not hand raw Tavily API keys to those downstream consumers.

Less common but supported advanced settings#

Most deployments do not need these immediately, but they are part of the supported runtime contract:

If your goal is local development, straightforward self-hosting, or a standard gateway deployment, you usually do not need these first.

One-page decision summary#

If you only want the shortest correct answer:

• local development: DEV_OPEN_ADMIN=true
• single-instance self-hosting: ADMIN_AUTH_BUILTIN_ENABLED=true + ADMIN_AUTH_BUILTIN_PASSWORD_HASH
• gateway integration: ADMIN_AUTH_FORWARD_ENABLED=true + FORWARD_AUTH_HEADER + FORWARD_AUTH_ADMIN_VALUE
• end-user web login: additionally enable LINUXDO_OAUTH_ENABLED=true
• downstream client access: always use th-<id>-<secret>, never raw Tavily API keys

Related reading#

• Quick Start
• HTTP API Guide
• Deployment & Anonymity
• FAQ & Troubleshooting
• Storybook