Configuration

kinetic-context uses JSON configuration files to manage OpenCode settings, packages, and projects.

OpenCode Configuration

The OpenCode configuration file controls which AI model and provider to use for answering questions about dependencies.

Location: ~/.kctx/opencode/config/opencode.json (or /config/opencode.json in Docker)

OpenRouter Example

{
  "$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"
}

Supported Providers

OpenCode supports multiple providers. See the OpenCode providers documentation for a complete list and configuration examples.

Common providers include:

• OpenRouter
• OpenAI
• Anthropic
• Google (Gemini)
• GitHub Copilot
• And more...

GitHub Copilot Authentication

To authenticate with GitHub Copilot, you need to connect to the local OpenCode instance running in the container.

Note: This is particularly useful if your employer restricts which AI providers you can use and only allows GitHub Copilot.

Authentication Steps

1. Start kinetic-context (if not already running):

   kctx start

2. Connect to the OpenCode instance:

   • Open your browser and navigate to http://localhost:7168
   • This is the OpenCode web interface running in the container

3. Authenticate with GitHub Copilot:

   • In the OpenCode interface, navigate to the provider settings
   • Select GitHub Copilot as your provider
   • Follow the authentication flow to sign in with your GitHub account
   • Complete the OAuth authentication process

4. Verify authentication:

   • Once authenticated, your GitHub Copilot credentials will be stored in the container's state directory (/state/opencode)
   • The authentication persists across container restarts because it's stored in the mounted state volume

5. Configure your opencode.json: After authenticating, you can configure GitHub Copilot in your ~/.kctx/opencode/config/opencode.json file. See the OpenCode GitHub Copilot documentation for the exact configuration format.

The authentication state is stored separately from your regular OpenCode instance (if you have one installed locally) thanks to the XDG_STATE_HOME=/state environment variable, which ensures the containerized OpenCode instance uses its own state directory.

Package Configuration

Package configuration files define which dependencies are available for querying.

Location: ~/.kctx/packages/ (or /packages/ in Docker)

Package Config Format

Each package needs a JSON configuration file. The filename should match the package identifier (e.g., @hookform/resolvers.json).

{
  "identifier": "@hookform/resolvers",
  "package_manager": "npm",
  "display_name": "React Hook Form - Resolvers",
  "default_tag": "master",
  "urls": {
    "website": "https://react-hook-form.com/",
    "docs": "https://react-hook-form.com/docs/useform#resolver",
    "git_browser": "https://github.com/react-hook-form/resolvers",
    "git": "git@github.com:react-hook-form/resolvers.git",
    "logo": ""
  }
}

Field Descriptions

• identifier (required): Unique identifier for the package (e.g., @hookform/resolvers, zod)
• package_manager (required): Package manager (e.g., npm, pnpm, yarn)
• display_name (required): Human-readable name for the package
• default_tag (required): Default git tag/branch to use when cloning (e.g., master, main, v1.0.0)
• urls.website (optional): Link to package website
• urls.docs (optional): Link to package documentation
• urls.git_browser (optional): Link to view repo in browser
• urls.git (required): Git URL to clone the repository (can be https:// or git@ SSH format)
• urls.logo (optional): Link to logo image file

Adding a Package

1. Create a JSON file in ~/.kctx/packages/ with the package identifier as the filename
2. Fill in the configuration with the package details
3. The repository will be cloned automatically when first queried

Package Repository Structure

After a package is cloned, the structure looks like:

/packages/
├── @hookform/
│   └── resolvers/          # Cloned git repository
├── @hookform/
│   └── resolvers.json      # Package configuration
└── zod/
    └── zod.json            # Package configuration

Local Packages

Local packages are stored in a separate directory (/local-packages/ or ~/.kctx/local-packages/). These are typically used for packages that are discovered via project scanning or packages that don't come from external git repositories.

Project Configuration

Project configuration files define which dependencies are associated with a project and which versions/tags to use.

Location: ~/.kctx/projects/ (or /projects/ in Docker)

Project Config Format

Each project needs a JSON configuration file. The filename should match the project identifier (e.g., my-project.json).

{
  "identifier": "my-project",
  "display_name": "My Project",
  "urls": {
    "website": "https://my-project.com",
    "git_browser": "https://github.com/user/my-project",
    "git": "git@github.com:user/my-project.git",
    "logo": ""
  },
  "dependencies": [
    {
      "identifier": "@hookform/resolvers",
      "tag": "master"
    },
    {
      "identifier": "zod",
      "tag": "v3.22.0"
    }
  ]
}

Field Descriptions

• identifier (required): Unique identifier for the project. This should match the directory name of your project when using the MCP server.
• display_name (required): Human-readable name for the project
• urls.website (optional): Link to project website
• urls.git_browser (optional): Link to view repo in browser
• urls.git (optional): Git URL for the project
• urls.logo (optional): Link to logo image file
• dependencies (required): Array of dependency objects, each containing:
  • identifier (required): Must match a package identifier from /packages
  • tag (optional): Git tag/branch to use for this dependency in this project. If not specified, uses the package's default_tag

Creating a Project

1. Create a JSON file in ~/.kctx/projects/ with your project identifier as the filename
2. Add the project details and list of dependencies
3. Each dependency can specify a specific tag/version, or use the package's default

Project-Dependency Versioning

Projects can override the default tag for dependencies. This allows you to:

• Pin specific versions for production projects
• Use different versions for different projects
• Test with beta/alpha versions

Example:

{
  "identifier": "production-app",
  "display_name": "Production App",
  "dependencies": [
    {
      "identifier": "zod",
      "tag": "v3.22.0"  // Pin to specific version
    }
  ]
}

vs.

{
  "identifier": "experimental-app",
  "display_name": "Experimental App",
  "dependencies": [
    {
      "identifier": "zod",
      "tag": "next"  // Use beta version
    }
  ]
}

Environment Variables

You can also configure kinetic-context using environment variables in your compose.yaml:

• CORS_ORIGIN: CORS origin URL (default: http://localhost:7167)
• NODE_ENV: Environment mode (default: production)
• PACKAGES_DIR: Path to packages directory (default: /packages)
• LOCAL_PACKAGES_DIR: Path to local packages directory (default: /local-packages)
• PROJECTS_DIR: Path to projects directory (default: /projects)
• OPENCODE_CONFIG_PATH: Path to opencode.json (default: /config/opencode.json)
• OPENCODE_URL: OpenCode service URL (default: http://opencode:4096)

Configuration Best Practices

1. Use descriptive identifiers - Make package and project identifiers clear and consistent
2. Pin versions for production - Use specific tags for production projects
3. Keep configs in version control - Consider backing up your configuration files
4. Document custom tags - If using non-standard tags, document why
5. Test configurations - Verify packages clone and checkout correctly