Getting Started

This guide will help you get kinetic-context up and running in just a few minutes.

Prerequisites

• Docker and Docker Compose installed
• A GitHub account (for authenticating to ghcr.io)
• A GitHub Personal Access Token with read:packages permission

Installation

Step 1: Create Directory Structure

Create the necessary directories:

mkdir -p ~/.kctx/{bin,config,data/{packages,projects}}

Step 2: Create Docker Compose File

Create ~/.kctx/compose.yaml:

version: '3.8'

services:
  opencode:
    image: ghcr.io/anomalyco/opencode:latest
    ports:
      - "7168:4096"
    volumes:
      - ~/.kctx/config:/config
      - ~/.kctx/data:/data
    command: ["serve", "--hostname=0.0.0.0"]
    environment:
      - OPENCODE_CONFIG=/config/opencode.json
    restart: unless-stopped

  kinetic-context:
    image: christopherkapic/kinetic-context:latest
    ports:
      - "7167:3000"
    volumes:
      - ~/.kctx/data:/data
      - ~/.kctx/config:/config
    environment:
      - CORS_ORIGIN=http://localhost:7167
      - NODE_ENV=production
      - PACKAGES_DIR=/data/packages
      - PROJECTS_DIR=/data/projects
      - OPENCODE_CONFIG_PATH=/config/opencode.json
      - OPENCODE_URL=http://opencode:4096
    depends_on:
      - opencode
    restart: unless-stopped

Step 3: Create OpenCode Configuration

Create ~/.kctx/config/opencode.json with your chosen provider. For example, with OpenRouter:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "your-actual-api-key-here"
      },
      "models": {
        "openrouter/anthropic/claude-3.5-sonnet": {
          "name": "Claude 3.5 Sonnet"
        }
      }
    }
  },
  "model": "openrouter/anthropic/claude-3.5-sonnet"
}

See the Configuration guide for more provider options.

Step 4: Create kctx Command

Create ~/.kctx/bin/kctx:

#!/bin/bash
docker compose -f ~/.kctx/compose.yaml "$@"

Make it executable:

chmod +x ~/.kctx/bin/kctx

Step 5: Authenticate to GitHub Container Registry

Before starting kinetic-context, you need to authenticate to GitHub Container Registry to pull the opencode image:

docker login ghcr.io

When prompted:

• Username: Your GitHub username
• Password: A GitHub Personal Access Token (PAT) with read:packages permission

To create a PAT:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a name (e.g., "kinetic-context")
4. Select the read:packages scope
5. Click "Generate token"
6. Copy the token and use it as the password when running docker login ghcr.io

Step 6: Add kctx to Your PATH

Add the kctx command to your PATH so you can use it from anywhere:

For bash (add to ~/.bashrc or ~/.bash_profile):

export PATH="$HOME/.kctx/bin:$PATH"

For zsh (add to ~/.zshrc):

export PATH="$HOME/.kctx/bin:$PATH"

Then reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Step 7: Start kinetic-context

Start the services:

kctx start

Or simply:

kctx

Step 8: Access the Web UI

Open your browser and navigate to:

http://localhost:7167

You should see the kinetic-context web interface!

Alternative: Automated Installation

If you prefer to use an automated setup script instead of manual installation:

bash <(curl -fsSL https://raw.githubusercontent.com/christopher-kapic/kinetic-context/master/setup.sh)

This script will:

• Create the ~/.kctx directory structure
• Generate a compose.yaml file
• Create the kctx executable script
• Set up example configuration files

After running the script, follow steps 5-8 above (authenticate, add to PATH, start services, and access the web UI).

Note: Manual installation is recommended for security best practices, as it gives you full visibility into what's being set up.

Next Steps

• Configure Packages - Add dependencies to query
• Create Projects - Set up projects with dependencies
• Use the MCP Server - Connect your AI coding tools
• Learn about Docker Setup - Advanced Docker configuration

Troubleshooting

Can't pull opencode image

Make sure you've authenticated to ghcr.io:

docker login ghcr.io

Services won't start

Check the logs:

kctx logs

Port already in use

Edit ~/.kctx/compose.yaml and change the port mappings if 7167 or 7168 are already in use.