CODITECT Docker Deployment Guide

Deploy CODITECT in your environment using licensed Docker containers.

Prerequisites

• Docker 20.10+ installed
• Active CODITECT license (purchase at coditect.ai)
• GCP service account credentials (for Artifact Registry access)

Quick Start

Step 1: Get Your License Key

1. Log in to dashboard.coditect.ai
2. Navigate to Settings → License
3. Copy your license key

Step 2: Authenticate with Artifact Registry

# Option A: Using gcloud (recommended)
gcloud auth configure-docker us-central1-docker.pkg.dev

# Option B: Using service account key
cat key.json | docker login -u _json_key --password-stdin \
  us-central1-docker.pkg.dev

Step 3: Verify Image Signature (Recommended)

CODITECT images are cryptographically signed. Verify before pulling:

# Install cosign
brew install cosign  # macOS
# or: https://docs.sigstore.dev/cosign/installation/

# Verify signature
cosign verify \
  --key gcpkms://projects/coditect-citus-prod/locations/us-central1/keyRings/coditect-container-signing/cryptoKeys/cosign-signing-key \
  us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest

Expected output:

Verification for us-central1-docker.pkg.dev/.../coditect-docker:latest --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

Step 4: Pull the Image

docker pull us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest

Step 5: Run CODITECT

docker run -it \
  -e CODITECT_LICENSE_KEY="your-license-key-here" \
  -v $(pwd):/home/developer/workspace \
  us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest

Configuration Options

Environment Variables

Variable	Required	Default	Description
CODITECT_LICENSE_KEY	Yes	-	Your license key
ANTHROPIC_API_KEY	Yes	-	Claude API key for AI features
CODITECT_API_URL	No	https://api.coditect.ai	License server URL
CODITECT_HEARTBEAT_INTERVAL	No	300	Heartbeat interval (seconds)

Volume Mounts

Mount	Purpose
/home/developer/workspace	Your project files
/home/developer/.config	Persist user configuration
/home/developer/.ssh	SSH keys for git

Example with All Options

docker run -it \
  -e CODITECT_LICENSE_KEY="lic_abc123..." \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -v $(pwd):/home/developer/workspace \
  -v ~/.ssh:/home/developer/.ssh:ro \
  -v ~/.gitconfig:/home/developer/.gitconfig:ro \
  -p 3000:3000 \
  -p 8080:8080 \
  us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest

Docker Compose

For persistent development environments, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  coditect:
    image: us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest
    environment:
      - CODITECT_LICENSE_KEY=${CODITECT_LICENSE_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/home/developer/workspace
      - ~/.ssh:/home/developer/.ssh:ro
      - ~/.gitconfig:/home/developer/.gitconfig:ro
      - coditect-config:/home/developer/.config
    ports:
      - "3000:3000"
      - "8080:8080"
    stdin_open: true
    tty: true

volumes:
  coditect-config:

Run with:

docker compose up -d
docker compose exec coditect zsh

License Tiers

Tier	Concurrent Sessions	API Rate Limit	Support
Starter	2	100 req/min	Community
Professional	10	1000 req/min	Email
Enterprise	Unlimited	Custom	Dedicated

Check your tier:

# Inside container
echo $CODITECT_TIER

Troubleshooting

License Validation Failed

ERROR: License validation failed: Invalid license key

Solutions:

1. Verify your license key at dashboard.coditect.ai
2. Check for extra whitespace in the key
3. Ensure your license hasn't expired

Container Exits Immediately

Container exited with code 1

Check logs:

docker logs <container-id>

Common causes:

• Missing CODITECT_LICENSE_KEY
• Invalid API key format
• Network connectivity to api.coditect.ai

Permission Denied on Workspace

Permission denied: /home/developer/workspace/...

Solutions:

# Fix ownership (run on host)
sudo chown -R $(id -u):$(id -g) ./workspace

# Or run container with matching UID
docker run -it --user $(id -u):$(id -g) ...

Cannot Pull Image

Error: unauthorized: You don't have permission

Solutions:

1. Re-authenticate: gcloud auth configure-docker us-central1-docker.pkg.dev
2. Verify your license includes Docker access
3. Contact support@coditect.ai

Signature Verification Failed

Error: no matching signatures

Solutions:

1. Ensure you're verifying a released version (not a dev build)
2. Check your network can reach Google Cloud KMS
3. Try with the public key file:

   curl -o cosign.pub https://coditect.ai/.well-known/cosign.pub
   cosign verify --key cosign.pub IMAGE:TAG

4. Verify the image digest matches the signed version

Note: If verification fails, do NOT pull the image. Contact support@coditect.ai immediately.

Security Notes

The CODITECT container implements the ADR-055 protection model:

• Signed Images - All images are cryptographically signed with Cosign and Cloud KMS
• Framework is read-only - You cannot modify files in /opt/coditect
• No sudo access - The developer user cannot escalate privileges
• License heartbeat - Session validity is checked every 5 minutes

Image Signing (Docker Content Trust)

All CODITECT images are signed using Cosign with a Google Cloud KMS key. This provides:

Protection	Threat Mitigated
Integrity	Detects if image was modified in transit or at registry
Authenticity	Confirms image was published by CODITECT
Non-repudiation	Cryptographic proof of publisher identity

Verify signatures:

cosign verify \
  --key gcpkms://projects/coditect-citus-prod/locations/us-central1/keyRings/coditect-container-signing/cryptoKeys/cosign-signing-key \
  us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:v1.0.0

For offline verification, download the public key:

curl -o cosign.pub https://coditect.ai/.well-known/cosign.pub
cosign verify --key cosign.pub IMAGE:TAG

This ensures framework integrity while giving you full access to your workspace.

Updating

Pull the latest image:

docker pull us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:latest

For specific versions:

docker pull us-central1-docker.pkg.dev/coditect-citus-prod/coditect-licensed/coditect-docker:v1.0.0

Support

• Documentation: docs.coditect.ai
• Email: support@coditect.ai
• Community: GitHub Discussions

Related

• GCP Cloud Workstations Guide
• Distribution Overview
• ADR-055: Container Protection Model

---

Version: 1.0.0 | Updated: 2026-01-05