Installation

There are two ways to install kinetic-context: manual installation (recommended) or using the automated setup script.

Manual Installation (Recommended)

Manual installation is the recommended approach as it gives you full visibility and control over what's being set up, and follows security best practices by avoiding running scripts from the internet.

Step 1: Create Directory Structure

mkdir -p ~/.kctx/{bin,packages,local-packages,projects,opencode/{config,state}}

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/opencode/config:/config
      - ~/.kctx/opencode/state:/state
      - ~/.kctx/packages:/packages
      - ~/.kctx/local-packages:/local-packages
    command: ["serve", "--hostname=0.0.0.0"]
    environment:
      - OPENCODE_CONFIG=/config/opencode.json
      - XDG_STATE_HOME=/state # separate state volume for persistence
      - OPENCODE_DISABLE_DEFAULT_PLUGINS=true
    restart: unless-stopped

  kinetic-context:
    image: docker.io/christopherkapic/kinetic-context:latest
    ports:
      - "7167:3000"
    volumes:
      - ~/.kctx/packages:/packages
      - ~/.kctx/local-packages:/local-packages
      - ~/.kctx/projects:/projects
      - ~/.kctx/opencode/config:/config
    environment:
      - CORS_ORIGIN=http://localhost:7167
      - NODE_ENV=production
      - PACKAGES_DIR=/packages
      - LOCAL_PACKAGES_DIR=/local-packages
      - PROJECTS_DIR=/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/opencode/config/opencode.json:

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

Step 4: Install kctx Command

Fetch and install the kctx command-line tool:

mkdir -p ~/.kctx/bin
curl -fsSL -o ~/.kctx/bin/kctx https://raw.githubusercontent.com/christopher-kapic/kinetic-context/master/kctx
chmod +x ~/.kctx/bin/kctx

Step 5: Authenticate to GitHub Container Registry (Optional)

Authenticating to GitHub Container Registry is optional. If you authenticate, the pre-built OpenCode image will be pulled from ghcr.io. If not, OpenCode will be built locally from source during the first startup.

docker login ghcr.io

Note: If you don't authenticate, the system will automatically build OpenCode from source instead. This requires bun to be installed.

Step 6: Start Services

kctx start

Or simply:

kctx

Automated Installation (Alternative)

If you prefer to use an automated setup script, you can use the installation script:

Quick Install

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

This script will:

Create the ~/.kctx directory structure
Generate a Docker Compose configuration file
Fetch the kctx command-line tool from GitHub

What Gets Installed

The installation script creates the following structure:

~/.kctx/
├── bin/
│   └── kctx              # Command-line tool
├── packages/             # Package repositories and configs
├── local-packages/       # Local package repositories
├── projects/             # Project configurations
├── opencode/
│   ├── config/
│   │   └── opencode.json # OpenCode configuration
│   └── state/            # OpenCode state (persists across restarts)
└── compose.yaml          # Docker Compose configuration

Post-Installation Steps

After running the script, you need to:

Authenticate to GitHub Container Registry (optional):
```
docker login ghcr.io
```
If you don't authenticate, OpenCode will be built locally from source. You'll need a GitHub Personal Access Token with read:packages permission. See Getting Started for details.
Configure OpenCode - Edit ~/.kctx/opencode/config/opencode.json with your API key
Add kctx to PATH - Add ~/.kctx/bin to your PATH environment variable
Start the services:
```
kctx start
```

Docker Image Tags

The kinetic-context Docker image is available on DockerHub:

docker.io/christopherkapic/kinetic-context:latest - Latest stable release
docker.io/christopherkapic/kinetic-context:0.1.0 - Specific version (example)

System Requirements

Docker: Version 20.10 or later
Docker Compose: Version 2.0 or later
Disk Space: At least 2GB free (for Docker images and package repositories)
Memory: 2GB RAM minimum (4GB recommended)

Platform Support

kinetic-context runs on:

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (via WSL2 or Docker Desktop)

Updating

To update to the latest version:

kctx update

This command will:

Update the kctx script to the latest version from GitHub
Pull the latest Docker images for both kinetic-context and opencode
Restart the services with the new images

To update only the kctx script (without updating Docker images):

kctx self-update

Uninstallation

To remove kinetic-context:

# Stop and remove containers
kctx down

# Remove the directory (optional)
rm -rf ~/.kctx

Note: This will delete all your configuration and data. Make sure to back up anything important first.

Installation

On this page