Configuration

Environment Variables

Configure xiantong through environment variables

Environment variables provide configuration and credentials for automation and server deployment scenarios.

Supported Variables#

ANTHROPIC_API_KEY / XIANTONG_ANTHROPIC_API_KEY#

Provide an Anthropic API key without storing it locally. Both names are supported; XIANTONG_ANTHROPIC_API_KEY takes precedence if both are set.

export ANTHROPIC_API_KEY="sk-ant-api03-..."
xiantong -p "Check my tasks"

XIANTONG_CLAUDE_OAUTH_TOKEN#

Provide a Claude OAuth token (for Claude Pro/Max subscriptions) without storing it locally.

export XIANTONG_CLAUDE_OAUTH_TOKEN="your-oauth-token"

ANTHROPIC_BASE_URL#

Override the API endpoint URL. This is set automatically by xiantong when you configure a non-Anthropic provider (OpenRouter, Vercel AI Gateway, Ollama, or custom endpoint) via the UI.

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

You can also set this manually to route all API calls through a custom endpoint:

# Use OpenRouter
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

# Use local Ollama
export ANTHROPIC_BASE_URL="http://localhost:11434"

This variable is typically managed by xiantong based on your API Provider configuration. You only need to set it manually for automation or CI scenarios.

AWS Credentials (Bedrock)#

When using AWS Bedrock with authType: "environment", the subprocess inherits standard AWS environment variables from your shell:

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."     # optional, for STS temporary credentials
export AWS_REGION="us-east-1"      # or set awsRegion in the connection config
export AWS_PROFILE="my-profile"    # use a named profile from ~/.aws/credentials

These follow the standard AWS SDK credential chain — ~/.aws/credentials, SSO sessions, IAM roles, and instance profiles all work.

With authType: "iam_credentials", credentials are entered in the UI and injected into the subprocess automatically. You do not need to set these env vars in that case.

XIANTONG_CONFIG_DIR#

Override the default configuration directory. By default, xiantong stores configuration in ~/.xiantong/.

export XIANTONG_CONFIG_DIR="/custom/path/to/config"

This affects the location of:

config.json
preferences.json
credentials.enc
Workspace configurations

XIANTONG_LOCAL_MCP_ENABLED#

Enable or disable local MCP server support (stdio subprocess servers).

export XIANTONG_LOCAL_MCP_ENABLED="false"

Value	Behavior
`"true"`	Enable local MCP servers (default when not set)
Any other value	Disable local MCP servers

This variable requires the exact lowercase string "true" to enable. Values like "True", "TRUE", "yes", or "1" will be treated as disabled.

This can also be configured per-workspace in the workspace settings.

XIANTONG_DEBUG#

Enable debug logging for troubleshooting. When set, additional diagnostic information is written to the log file.

export XIANTONG_DEBUG="true"

Server Mode Variables#

These configure the remote server when running in standalone or embedded mode.

XIANTONG_SERVER_TOKEN#

Bearer token for server authentication. Required for both server and client.

export XIANTONG_SERVER_TOKEN=$(openssl rand -hex 32)

XIANTONG_SERVER_URL#

Server URL for client connections. Set this on the client side to connect to a remote server.

export XIANTONG_SERVER_URL=wss://your-server:9100

XIANTONG_RPC_HOST#

Bind address for the server. Defaults to 127.0.0.1 (localhost only). Set to 0.0.0.0 to accept remote connections.

export XIANTONG_RPC_HOST=0.0.0.0

XIANTONG_RPC_PORT#

Server port. Defaults to 9100.

export XIANTONG_RPC_PORT=9100

XIANTONG_RPC_TLS_CERT / XIANTONG_RPC_TLS_KEY#

PEM certificate and private key files for TLS. Required for remote connections (wss://). Can be omitted for localhost development.

export XIANTONG_RPC_TLS_CERT=/path/to/cert.pem
export XIANTONG_RPC_TLS_KEY=/path/to/key.pem

XIANTONG_RPC_TLS_CA#

Optional PEM CA chain file for custom certificate authorities.

export XIANTONG_RPC_TLS_CA=/path/to/ca.pem

Development Variables#

These variables are primarily used for development and multi-instance scenarios.

XIANTONG_VITE_PORT#

Override the Vite dev server port. Automatically set when running from numbered instance folders.

export XIANTONG_VITE_PORT="5173"

XIANTONG_APP_NAME#

Override the application display name. Useful for distinguishing multiple instances.

export XIANTONG_APP_NAME="xiantong [Dev]"

XIANTONG_INSTANCE_NUMBER#

Instance identifier for multi-instance support. When set, adds a badge to the dock icon.

export XIANTONG_INSTANCE_NUMBER="1"

XIANTONG_DEEPLINK_SCHEME#

Custom deep link URL scheme. Default is xiantong.

export XIANTONG_DEEPLINK_SCHEME="xiantong1"

VITE_DEV_SERVER_URL#

URL of the Vite development server. Used internally during development.

export VITE_DEV_SERVER_URL="http://localhost:5173"

Precedence#

For API credentials, the lookup order is:

XIANTONG_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY environment variable
XIANTONG_CLAUDE_OAUTH_TOKEN environment variable (for OAuth)
Stored credential in ~/.xiantong/credentials.enc
Interactive prompt (if running interactively)

For API base URL:

ANTHROPIC_BASE_URL environment variable
Connection base URL (configured in LLM connections)
Default (https://api.anthropic.com)

For model selection:

LLM connection default model (if set)
App-level model defaults (per provider)
System default (Claude Sonnet)

For configuration directory:

XIANTONG_CONFIG_DIR environment variable
Default ~/.xiantong/

Usage Examples#

CI/CD Pipeline#

#!/bin/bash
export ANTHROPIC_API_KEY="${SECRETS_ANTHROPIC_KEY}"

xiantong -w "Work" -p "Generate release notes from recent commits"

Docker Container#

ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ENV XIANTONG_CONFIG_DIR=/app/config

CMD ["xiantong", "-w", "default", "-p", "..."]

Temporary Override#

Use a different API key for one command:

ANTHROPIC_API_KEY="sk-ant-different-key" xiantong -p "Quick check"

Custom Configuration Directory#

export XIANTONG_CONFIG_DIR="/home/user/.config/xiantong"
xiantong -p "Using custom config location"

Security Notes#

Avoid putting API keys directly in shell history or scripts. Use secret managers or secure environment injection.

Secure alternatives:

# Read from file
export ANTHROPIC_API_KEY=$(cat ~/.secrets/anthropic-key)

# Read from secret manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value --secret-id anthropic-key --query SecretString --output text)

# Use .env file (not committed to git)
source .env && xiantong -p "..."