Skip to main content

Installation

Get Tokligence Gateway running on your platform.

Requirements​

  • Go 1.24 or newer (for building from source)
  • Make (optional, for convenience targets)
  • Node.js 18+ (only if you build the optional frontend)

Installation Methods​

Python (pip)​

pip install tokligence

Node.js (npm)​

npm i -g @tokligence/gateway

From Source​

git clone https://github.com/tokligence/tokligence-gateway
cd tokligence-gateway
make build
# Binaries are placed in ./bin

Docker​

# Personal edition (no authentication)
docker pull ghcr.io/tokligence/gateway:personal-latest

# Team edition (with authentication)
docker pull ghcr.io/tokligence/gateway:team-latest

Running the Gateway​

Start the Daemon​

# From binary
./bin/gatewayd

# Or via npm
tgw start

# Default address: http://localhost:8081

Verify Installation​

# Test with loopback model (no external LLM needed)
curl -H "Authorization: Bearer test" \
     -H "Content-Type: application/json" \
     -d '{"model":"loopback","messages":[{"role":"user","content":"Hello"}]}' \
     http://localhost:8081/v1/chat/completions

The built-in loopback model echoes input without calling external LLMs, ideal for verifying connectivity.

Configuration​

LLM Provider Setup​

Configure an LLM endpoint before using the gateway:

Option 1: Local LLMs (Free)​

# Using Ollama (https://ollama.ai)
ollama serve
ollama run llama3
tgw chat "Hello!"

Option 2: Commercial APIs​

# OpenAI
export TOKLIGENCE_OPENAI_API_KEY=sk-...
tgw chat "Hello!"

# Anthropic
export TOKLIGENCE_ANTHROPIC_API_KEY=sk-ant-...
tgw chat "Hello!"

# Google
export TOKLIGENCE_GOOGLE_API_KEY=AIza...
tgw chat "Hello!"

Option 3: Custom Endpoint​

export TOKLIGENCE_LLM_ENDPOINT=http://your-llm.com/v1
export TOKLIGENCE_LLM_API_KEY=optional-key
tgw chat "Hello!"

Configuration Files​

Configuration loads in three layers:

  1. Global defaults: config/setting.ini
  2. Environment overlays: config/{dev,test,live}/gateway.ini
  3. Environment variables: TOKLIGENCE_* (highest priority)

Common Options​

OptionEnvironment VariableDefaultDescription
http_address—:8081HTTP bind address
identity_pathTOKLIGENCE_IDENTITY_PATH~/.tokligence/identity.dbUser DB path
ledger_pathTOKLIGENCE_LEDGER_PATH~/.tokligence/ledger.dbUsage ledger DB
log_file_daemonTOKLIGENCE_LOG_FILE_DAEMON—Daemon log file

Understanding API Keys​

Tokligence Gateway uses two types of API keys:

1. Gateway API Keys (User Authentication)​

Keys you create for users to access your gateway:

# Create a gateway API key for a user
./bin/gateway admin api-keys create --user <user_id>
# Returns: tok_xxxxxxxxxxxx
  • Purpose: Authenticate users/applications to your gateway
  • Format: tok_xxxxxxxxxxxx
  • Used in: Authorization: Bearer tok_xxxxxxxxxxxx

2. LLM Provider API Keys (Backend Connection)​

Keys from external LLM providers:

export TOKLIGENCE_OPENAI_API_KEY=sk-...       # From OpenAI
export TOKLIGENCE_ANTHROPIC_API_KEY=sk-ant-...  # From Anthropic
export TOKLIGENCE_GOOGLE_API_KEY=AIza...       # From Google

How They Work Together​

Client          Gateway API Key        Tokligence Gateway     LLM Provider Key      OpenAI/Anthropic
  │ ────────────────────────────────▶      │ ────────────────────────────────▶     │
  │     tok_xxxxxxxxxxxx                   │       sk-proj-...                     │

Next Steps​