Docker Containers - TealTiger Docs

TealTiger provides official Docker images for both Python and TypeScript SDKs. Use containers for consistent deployments, CI/CD pipelines, development environments, and serverless functions.

Why use Docker?

Consistent environments - Same runtime across dev, staging, and production
Fast onboarding - Get started in 5 minutes instead of 2 hours
CI/CD ready - Drop-in containers for GitHub Actions, GitLab CI, Jenkins
Serverless compatible - Deploy to AWS Lambda, Google Cloud Run, Azure Functions
Multi-platform - Supports both amd64 and arm64 architectures

Quick Start

docker pull ghcr.io/tealtiger/python-sdk:latest

# Run interactively
docker run -it --rm \
  -e OPENAI_API_KEY=your-key \
  ghcr.io/tealtiger/python-sdk:latest \
  python

# Pull the latest image
docker pull ghcr.io/tealtiger/typescript-sdk:latest

# Run interactively
docker run -it --rm \
  -e OPENAI_API_KEY=your-key \
  ghcr.io/tealtiger/typescript-sdk:latest \
  node

Available Images

Python SDK

Variant	Image	Size	Use Case
Production	`ghcr.io/tealtiger/python-sdk:latest`	~605MB	Production deployments, serverless
Development	`ghcr.io/tealtiger/python-sdk:dev`	~960MB	Local development with tools
Alpine	`ghcr.io/tealtiger/python-sdk:alpine`	~530MB	Minimal production deployments
Jupyter	`ghcr.io/tealtiger/python-sdk:jupyter`	~1.23GB	Interactive experimentation

TypeScript SDK

Variant	Image	Size	Use Case
Production	`ghcr.io/tealtiger/typescript-sdk:latest`	~428MB	Production deployments, serverless
Development	`ghcr.io/tealtiger/typescript-sdk:dev`	~TBD	Local development with tools

All images support both amd64 (Intel/AMD) and arm64 (Apple Silicon, AWS Graviton) architectures.

Image Variants Explained

Production

Optimized for production deployments with minimal size and maximum security. Features:

Multi-stage build for smaller image size
Non-root user execution
Production dependencies only
No development tools

Best for:

Production deployments
Serverless functions (Lambda, Cloud Run)
Container orchestration (Kubernetes, ECS)
CI/CD test runners

Development

Includes development tools for local development and testing. Features:

All production features
Development tools (pytest, mypy, black, eslint, typescript)
Git and vim for editing
VS Code dev container support

Best for:

Local development
VS Code dev containers
Testing and debugging
CI/CD with linting/type checking

Alpine (Python only)

Minimal production image based on Alpine Linux. Features:

Smallest image size (~530MB)
Alpine Linux base
Full SDK functionality
Production-ready

Best for:

Size-constrained deployments
Edge computing
IoT devices
Cost optimization (faster pulls)

Jupyter (Python only)

Interactive development environment with Jupyter Lab. Features:

Jupyter Lab pre-installed
Data science tools (pandas, numpy)
Port 8888 exposed
Notebook examples included

Best for:

Interactive experimentation
Data analysis
Prototyping
Training and demos

Usage Examples

Run Your Script

Mount your code and run it in a container.

docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/python-sdk:latest \
  python my_script.py

docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/typescript-sdk:latest \
  node my_script.js

Interactive Shell

Start an interactive Python or Node.js shell.

docker run -it --rm \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/python-sdk:latest \
  python

# In Python:
>>> from tealtiger import TealOpenAI
>>> client = TealOpenAI(api_key="sk-xxx")

docker run -it --rm \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/typescript-sdk:latest \
  node

// In Node.js:
> const { TealOpenAI } = require('tealtiger');
> const client = new TealOpenAI({ apiKey: 'sk-xxx' });

Jupyter Notebook

Start Jupyter Lab for interactive development.

docker run -p 8888:8888 \
  -e OPENAI_API_KEY=sk-xxx \
  -v $(pwd)/notebooks:/app/notebooks \
  ghcr.io/tealtiger/python-sdk:jupyter

# Open browser to http://localhost:8888

Development Environment

Start a development container with all tools.

docker run -it --rm \
  -v $(pwd):/app \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/python-sdk:dev \
  bash

# Inside container:
$ pytest tests/
$ black src/
$ mypy src/

docker run -it --rm \
  -v $(pwd):/app \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/typescript-sdk:dev \
  bash

# Inside container:
$ npm test
$ npm run lint
$ npm run build

Docker Compose

Create a docker-compose.yml file for easier management.

version: '3.8'

services:
  tealtiger:
    image: ghcr.io/tealtiger/python-sdk:latest
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: python my_script.py

version: '3.8'

services:
  tealtiger:
    image: ghcr.io/tealtiger/typescript-sdk:latest
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: node my_script.js

Run with:

docker-compose run tealtiger

CI/CD Integration

GitHub Actions

name: Test with TealTiger

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/tealtiger/python-sdk:latest

    steps:
      - uses: actions/checkout@v3

      - name: Run tests
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python -m pytest tests/

name: Test with TealTiger

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/tealtiger/typescript-sdk:latest

    steps:
      - uses: actions/checkout@v3

      - name: Run tests
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: npm test

GitLab CI

test:
  image: ghcr.io/tealtiger/python-sdk:latest
  script:
    - python -m pytest tests/
  variables:
    OPENAI_API_KEY: $OPENAI_API_KEY

test:
  image: ghcr.io/tealtiger/typescript-sdk:latest
  script:
    - npm test
  variables:
    OPENAI_API_KEY: $OPENAI_API_KEY

Environment Variables

All TealTiger Docker images support these environment variables:

Variable	Description	Required
`OPENAI_API_KEY`	OpenAI API key	For OpenAI
`ANTHROPIC_API_KEY`	Anthropic API key	For Anthropic
`GOOGLE_API_KEY`	Google Gemini API key	For Gemini
`AWS_ACCESS_KEY_ID`	AWS access key	For Bedrock
`AWS_SECRET_ACCESS_KEY`	AWS secret key	For Bedrock
`AWS_REGION`	AWS region	For Bedrock
`COHERE_API_KEY`	Cohere API key	For Cohere
`MISTRAL_API_KEY`	Mistral API key	For Mistral
`AZURE_OPENAI_API_KEY`	Azure OpenAI key	For Azure
`AZURE_OPENAI_ENDPOINT`	Azure endpoint	For Azure

Security Best Practices

Non-Root User

All images run as non-root user for security.

# Verify non-root user
docker run --rm ghcr.io/tealtiger/python-sdk:latest whoami
# Output: tealtiger

# Verify non-root user
docker run --rm ghcr.io/tealtiger/typescript-sdk:latest whoami
# Output: node

Resource Limits

Limit CPU and memory usage.

docker run --rm \
  --cpus="0.5" \
  --memory="512m" \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/python-sdk:latest \
  python my_script.py

Read-Only Filesystem

Run with read-only filesystem for extra security.

docker run --rm \
  --read-only \
  --tmpfs /tmp:size=100M \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/tealtiger/python-sdk:latest \
  python my_script.py

Secrets Management

Never hardcode secrets in images. Use environment variables or secret managers.

# Good: Use environment variables
docker run --rm \
  -e OPENAI_API_KEY=$(cat ~/.openai/key) \
  ghcr.io/tealtiger/python-sdk:latest \
  python my_script.py

# Better: Use Docker secrets (Swarm/Kubernetes)
docker service create \
  --secret openai_key \
  ghcr.io/tealtiger/python-sdk:latest

VS Code Dev Containers

Use TealTiger images with VS Code dev containers for consistent development environments.

Setup

Install the Dev Containers extension in VS Code
Create .devcontainer/devcontainer.json:

{
  "name": "TealTiger Python Dev",
  "image": "ghcr.io/tealtiger/python-sdk:dev",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "ms-python.black-formatter"
      ],
      "settings": {
        "python.linting.enabled": true,
        "python.linting.pylintEnabled": true,
        "python.formatting.provider": "black"
      }
    }
  },
  "forwardPorts": [8888],
  "postCreateCommand": "pip install -e .",
  "remoteUser": "tealtiger"
}

{
  "name": "TealTiger TypeScript Dev",
  "image": "ghcr.io/tealtiger/typescript-sdk:dev",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "remoteUser": "node"
}

Open Command Palette (Ctrl+Shift+P)
Select Dev Containers: Reopen in Container

Building Locally

Build images locally for customization or testing.

# Clone the repository
git clone https://github.com/agentguard-ai/tealtiger-python.git
cd tealtiger-python

# Build production image
docker build -t tealtiger/python-sdk:latest .

# Build dev image
docker build -t tealtiger/python-sdk:dev -f Dockerfile.dev .

# Build Alpine image
docker build -t tealtiger/python-sdk:alpine -f Dockerfile.alpine .

# Build Jupyter image
docker build -t tealtiger/python-sdk:jupyter -f Dockerfile.jupyter .

# Clone the repository
git clone https://github.com/agentguard-ai/tealtiger-typescript.git
cd tealtiger-typescript

# Build production image
docker build -t tealtiger/typescript-sdk:latest .

# Build dev image
docker build -t tealtiger/typescript-sdk:dev -f Dockerfile.dev .

Troubleshooting

Image Pull Fails

If GHCR is unavailable, try Docker Hub:

# Python
docker pull docker.io/tealtiger/python-sdk:latest

# TypeScript
docker pull docker.io/tealtiger/typescript-sdk:latest

Permission Denied

Run as your current user:

docker run --rm \
  --user $(id -u):$(id -g) \
  -v $(pwd):/workspace \
  ghcr.io/tealtiger/python-sdk:latest \
  python my_script.py

Import Errors

Verify the SDK is installed:

docker run --rm ghcr.io/tealtiger/python-sdk:latest \
  python -c "import tealtiger; print(tealtiger.__version__)"

docker run --rm ghcr.io/tealtiger/typescript-sdk:latest \
  node -e "console.log(require('tealtiger'))"

Slow Builds

Use Docker BuildKit for faster builds:

export DOCKER_BUILDKIT=1
docker build -t my-image .

Performance

Image Sizes

SDK	Production	Dev	Alpine	Jupyter
Python	605MB	960MB	530MB	1.23GB
TypeScript	428MB	TBD	N/A	N/A

Build Times

Cold cache: 2-10 minutes
Warm cache: 1-3 minutes
Container start: <2 seconds

Pull Times

Fast connection (100 Mbps): 10-30 seconds
Average connection (25 Mbps): 30-90 seconds
Slow connection (5 Mbps): 2-5 minutes

Governance Sidecar (v1.2)

New in v1.2.0. The governance sidecar wraps TealEngine v1.2 as a language-agnostic HTTP API. Any agent — Go, Rust, Java, Python, or TypeScript — can call the sidecar over HTTP to get governance decisions without importing the SDK.

Sidecar Quick Start

# Pull the governance sidecar image
docker pull tealtigeradmin/tealtiger-typescript:1.2-governance

# Run with default settings
docker run -p 8080:8080 tealtigeradmin/tealtiger-typescript:1.2-governance

# Test the health endpoint
curl http://localhost:8080/health
# {"status":"ok","version":"1.2.0","mode":"ENFORCE","uptime_seconds":2}

Sidecar Endpoints

The sidecar exposes 6 HTTP endpoints:

Method	Path	Description
`POST`	`/evaluate`	Policy evaluation — returns a full Decision
`POST`	`/validate`	TEEC validation — check a Decision against the evidence contract
`POST`	`/scan`	Secret detection — scan content for leaked credentials
`GET`	`/health`	Health check — returns status, version, mode, uptime
`GET`	`/ready`	Readiness probe — returns `{ "ready": true }` when engine is initialized
`GET`	`/modules`	List active governance modules and their status

POST /evaluate

Evaluate a request against the configured policy. Returns a full v1.2 Decision.

curl -X POST http://localhost:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "correlation_id": "req-abc-123",
    "agent_id": "agent-001",
    "user_id": "user-456",
    "request": {
      "content": "Process this order",
      "tool": "database_query",
      "model": "gpt-4"
    }
  }'

Response:

{
  "correlation_id": "req-abc-123",
  "decision": {
    "action": "ALLOW",
    "reason_codes": ["POLICY_COMPLIANT"],
    "risk_score": 0,
    "mode": "ENFORCE",
    "event_type": "policy.evaluation",
    "teec_version": "0.1.0",
    "correlation_id": "req-abc-123",
    "reason": "Request allowed — all governance checks passed",
    "metadata": {
      "evaluation_time_ms": 3,
      "modules_evaluated": ["tealregistry"],
      "modules_failed": []
    }
  }
}

POST /validate

Validate a Decision object against the TEEC evidence contract.

curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d '{
    "decision": {
      "action": "DENY",
      "reason_codes": ["SECRET_DETECTED"],
      "event_type": "secret.detection",
      "correlation_id": "req-001"
    }
  }'

POST /scan

Scan content for secrets. Returns findings and a governance action.

curl -X POST http://localhost:8080/scan \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My API key is sk-proj-abc123def456ghi789",
    "correlation_id": "scan-001"
  }'

Response:

{
  "correlation_id": "scan-001",
  "findings": [
    {
      "finding_id": "f-abc123",
      "type": "openai_api_key",
      "category": "api_keys",
      "confidence": 0.95,
      "severity": "critical",
      "fingerprint": "sha256:a1b2c3..."
    }
  ],
  "action": "DENY",
  "risk_score": 100
}

Sidecar Environment Variables

Variable	Default	Description
`TEALTIGER_PORT`	`8080`	HTTP server port
`TEALTIGER_HOST`	`0.0.0.0`	Bind address
`TEALTIGER_POLICY_DIR`	`/etc/tealtiger/policies`	Directory for policy JSON files
`TEALTIGER_MODE`	`ENFORCE`	Policy mode: `ENFORCE`, `MONITOR`, or `REPORT_ONLY`
`TEALTIGER_LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`
`TEALTIGER_MAX_BODY_BYTES`	`1048576`	Maximum request body size (1MB default)

Mounting Policy Files

Mount your policy JSON files into the sidecar container:

# Create a policy directory
mkdir -p ./policies

# Create a policy file
cat > ./policies/governance.json << 'EOF'
{
  "secrets": { "enabled": true, "confidence_threshold": 0.8 },
  "registry": {
    "models": ["gpt-4", "gpt-4o", "claude-3-sonnet"],
    "tools": ["web_search", "file_read"]
  },
  "memory": { "default_scope": "session", "classification": "internal" }
}
EOF

# Run with mounted policies
docker run -p 8080:8080 \
  -v $(pwd)/policies:/etc/tealtiger/policies:ro \
  -e TEALTIGER_MODE=ENFORCE \
  tealtigeradmin/tealtiger-typescript:1.2-governance

Docker Compose with Sidecar

Run the governance sidecar alongside your application:

version: '3.8'

services:
  # Your application
  app:
    build: .
    environment:
      - TEALTIGER_SIDECAR_URL=http://governance:8080
    depends_on:
      governance:
        condition: service_healthy

  # TealTiger governance sidecar
  governance:
    image: tealtigeradmin/tealtiger-typescript:1.2-governance
    ports:
      - "8080:8080"
    environment:
      - TEALTIGER_MODE=ENFORCE
      - TEALTIGER_LOG_LEVEL=info
    volumes:
      - ./policies:/etc/tealtiger/policies:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M

Sidecar Health Checks

The sidecar provides two health endpoints for container orchestration:

GET /health — Liveness probe. Returns 200 with status, version, mode, and uptime.
GET /ready — Readiness probe. Returns 200 when the engine is initialized and ready to accept requests.

# Kubernetes liveness/readiness probes
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 5

Calling the Sidecar from Any Language

The sidecar is language-agnostic. Here are examples in different languages:

import httpx

async def evaluate(content: str, tool: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8080/evaluate",
            json={
                "request": {"content": content, "tool": tool},
                "agent_id": "my-agent"
            }
        )
        return response.json()["decision"]

func evaluate(content, tool string) (*Decision, error) {
    body, _ := json.Marshal(map[string]interface{}{
        "request": map[string]string{
            "content": content,
            "tool":    tool,
        },
        "agent_id": "my-agent",
    })
    resp, err := http.Post(
        "http://localhost:8080/evaluate",
        "application/json",
        bytes.NewReader(body),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    var result struct{ Decision Decision `json:"decision"` }
    json.NewDecoder(resp.Body).Decode(&result)
    return &result.Decision, nil
}

curl -X POST http://localhost:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{"request": {"content": "Hello", "tool": "web_search"}}'

Next Steps

Quickstart

Get started with TealTiger in 10 minutes

CI/CD Examples

Integrate TealTiger into your CI/CD pipeline

Kubernetes

Deploy TealTiger on Kubernetes

Serverless

Run TealTiger on AWS Lambda, Cloud Run, Azure Functions

Support

GitHub Issues: Python | TypeScript
Docker Hub: Python | TypeScript
GHCR: Python | TypeScript
Email: [email protected]

​Why use Docker?

​Quick Start

​Available Images

​Python SDK

​TypeScript SDK

​Image Variants Explained

​Production

​Development

​Alpine (Python only)

​Jupyter (Python only)

​Usage Examples

​Run Your Script

​Interactive Shell

​Jupyter Notebook

​Development Environment

​Docker Compose

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Environment Variables

​Security Best Practices

​Non-Root User

​Resource Limits

​Read-Only Filesystem

​Secrets Management

​VS Code Dev Containers

​Setup

​Building Locally

​Troubleshooting

​Image Pull Fails

​Permission Denied

​Import Errors

​Slow Builds

​Performance

​Image Sizes

​Build Times

​Pull Times

​Governance Sidecar (v1.2)

​Sidecar Quick Start

​Sidecar Endpoints

​POST /evaluate

​POST /validate

​POST /scan

​Sidecar Environment Variables

​Mounting Policy Files

​Docker Compose with Sidecar

​Sidecar Health Checks

​Calling the Sidecar from Any Language

​Next Steps

Quickstart

CI/CD Examples

Kubernetes

Serverless

​Support

Why use Docker?

Quick Start

Available Images

Python SDK

TypeScript SDK

Image Variants Explained

Production

Development

Alpine (Python only)

Jupyter (Python only)

Usage Examples

Run Your Script

Interactive Shell

Jupyter Notebook

Development Environment

Docker Compose

CI/CD Integration

GitHub Actions

GitLab CI

Environment Variables

Security Best Practices

Non-Root User

Resource Limits

Read-Only Filesystem

Secrets Management

VS Code Dev Containers

Setup

Building Locally

Troubleshooting

Image Pull Fails

Permission Denied

Import Errors

Slow Builds

Performance

Image Sizes

Build Times

Pull Times

Governance Sidecar (v1.2)

Sidecar Quick Start

Sidecar Endpoints

POST /evaluate

POST /validate

POST /scan

Sidecar Environment Variables

Mounting Policy Files

Docker Compose with Sidecar

Sidecar Health Checks

Calling the Sidecar from Any Language

Next Steps

Support