Skip to content

Installation & Setup

Get TokenPak up and running in minutes.

System Requirements

  • Python: 3.10+
  • OS: Linux, macOS, Windows
  • Disk: ~50 MB for package + dependencies
  • RAM: 512 MB minimum (1+ GB recommended for monitoring dashboard)
  • Internet: Required for API provider access

Step 1: Install via pip

Basic Installation

pip install tokenpak

Verify Installation

tokenpak --version
# Output: tokenpak 1.7.1

(Optional) Install with Extras

TokenPak can optionally integrate with popular frameworks. These are NOT required but make integration easier:

# For LangChain integration
pip install tokenpak[langchain]

# For CrewAI integration
pip install tokenpak[crewai]

# For agentic frameworks
pip install tokenpak[agentic]

# All extras
pip install tokenpak[all]

If you skip extras, you can always add them later by upgrading.

Step 2: Set Your API Keys

TokenPak needs API credentials for the providers you plan to use. Set these as environment variables:

Anthropic (Claude)

export ANTHROPIC_API_KEY="sk-ant-..."

Get your API key: https://console.anthropic.com

OpenAI

export OPENAI_API_KEY="sk-..."

Get your API key: https://platform.openai.com/account/api-keys

Google Gemini

export GOOGLE_API_KEY="AIza..."

Get your API key: https://makersuite.google.com/app/apikey

(Optional) Save to .env File

For development, create a .env file in your project:

# .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

Then load it before running:

set -a
source .env
set +a

Or use Python's python-dotenv:

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()  # Loads .env automatically

Step 3: Start the Proxy Server

TokenPak runs as a local proxy server on port 8766 (configurable).

Start the Server

tokenpak start

(tokenpak serve is also accepted as an alias.)

Output: 

[2026-05-17 09:00:00] TokenPak Proxy v1.7.1 starting...
[2026-05-15 09:00:00] Listening on http://127.0.0.1:8766
[2026-05-15 09:00:00] Ready to proxy requests

The server is now running and ready to accept requests.

(Optional) Custom Port

tokenpak start --port 9000

(Optional) Background Mode

nohup tokenpak start &
# or
tokenpak start --background

(Optional) With Dashboard

tokenpak dashboard

Shows a real-time dashboard of cost, token counts, and request history. The running proxy also serves a built-in HTML dashboard at http://127.0.0.1:8766/dashboard.

Step 4: Test the Installation

Python Client

Create test_tokenpak.py using the standard Anthropic SDK pointed at the proxy:

import anthropic

# Point the standard Anthropic SDK at the local TokenPak proxy
client = anthropic.Anthropic(
    base_url="http://127.0.0.1:8766",  # Your proxy
    api_key="sk-ant-...",              # Your API key
)

# Make a request
response = client.messages.create(
    model="claude-opus-4-8",
    messages=[
        {"role": "user", "content": "Say 'TokenPak is working!' in one sentence."}
    ],
    max_tokens=100
)

print("✅ TokenPak works!")
print(f"Response: {response.content[0].text}")

(Alternatively, use the TokenPak SDK adapter: from tokenpak.sdk import AnthropicAdapter.)

Run it:

python test_tokenpak.py

Expected output: 

✅ TokenPak works!
Response: TokenPak is working!

Using curl

curl -X POST http://127.0.0.1:8766/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-ant-..." \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Step 5: (Optional) Basic Configuration

TokenPak works out-of-the-box with defaults, but you can customize it with a config.yaml file.

Create config.yaml

# config.yaml

# Proxy settings
proxy:
  port: 8766
  host: 127.0.0.1

# Default provider
provider: anthropic  # or: openai, google, passthrough

# Fallback chain (try these if primary fails)
fallback:
  - anthropic
  - google
  - openai

# Compression settings
compression:
  enabled: true
  min_tokens: 1000  # Only compress if >1000 tokens

# Telemetry (cost tracking, logging)
telemetry:
  enabled: true
  log_file: "/tmp/tokenpak.log"

# Vault integration (optional)
vault:
  enabled: false
  root: "~/my-vault"
  index_file: "~/.tokenpak/vault-index.json"

Then run:

tokenpak start --config config.yaml

See Feature Matrix for full configuration options.

Troubleshooting

"ImportError: No module named 'tokenpak'"

Cause: TokenPak not installed Fix: 

pip install tokenpak

"Connection refused (127.0.0.1:8766)"

Cause: Proxy server not running Fix: 

tokenpak start
# (in another terminal)

"ANTHROPIC_API_KEY not set"

Cause: Environment variable missing Fix: 

export ANTHROPIC_API_KEY="sk-ant-..."
# Then start the proxy
tokenpak start

"Port 8766 already in use"

Cause: Another process using port 8766 Fix: 

# Use a different port
tokenpak start --port 9000

# Or kill the process using 8766
lsof -i :8766
kill <pid>

"YAML parsing error in config.yaml"

Cause: Malformed YAML syntax Fix: - Check indentation (use spaces, not tabs) - Validate at https://yamllint.com/ - See example config.yaml above

For more help, see Error Handling Guide.

Next Steps

✅ Installation complete!

Uninstall

pip uninstall tokenpak

(No configuration files are left behind.)