Self-Hosted Setup

If you’re running Kodus on your own infrastructure, the CLI works the same way — you just need to point it to your API.

Connect to Your Instance

Set the API URL

Tell the CLI where your Kodus API lives. Pick one method:

Environment Variable (Recommended)
Config File
Inline (One-off)

export KODUS_API_URL=https://kodus-api.yourcompany.com

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent:

echo 'export KODUS_API_URL=https://kodus-api.yourcompany.com' >> ~/.zshrc
source ~/.zshrc

Create or edit ~/.kodus/config.json:

{
  "apiUrl": "https://kodus-api.yourcompany.com",
  "teamKey": "kodus_xxxxx",
  "teamName": "Your Team",
  "organizationName": "Your Org"
}

The CLI creates this file automatically when you run kodus auth team-key, but you can also create it manually.

KODUS_API_URL=https://kodus-api.yourcompany.com kodus review

HTTPS is required. The CLI rejects non-HTTPS URLs for security. The only exception is localhost and 127.0.0.1 for local development.

Priority order: KODUS_API_URL env var > ~/.kodus/config.json apiUrl > default (https://api.kodus.io).

Authenticate

Team Key (Recommended)
Personal Login
CI/CD Token

Generate a team key from your self-hosted Kodus dashboard and configure it:

kodus auth team-key --key kodus_xxxxx

Or use the installer with both API URL and team key:

curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx

Team keys are ideal for shared environments and AI agent setups — no individual login required.

Generate a token from a personal account, then use it in pipelines:

# Generate (once, from a logged-in machine)
kodus auth token

# Use in your pipeline
export KODUS_API_URL=https://kodus-api.yourcompany.com
export KODUS_TOKEN=<generated-token>
kodus review --format json --fail-on error

Verify the Connection

kodus auth status

You should see your authentication mode, organization name, and that the token is valid. If using verbose mode, the API URL being used is logged:

kodus auth status --verbose

Cloudflare Access (Zero Trust)

If your self-hosted API is behind Cloudflare Access, the CLI supports service token authentication.

Environment Variables
Config File

export KODUS_API_URL=https://kodus-api.yourcompany.com
export CF_ACCESS_CLIENT_ID=your-client-id.access
export CF_ACCESS_CLIENT_SECRET=your-client-secret

{
  "apiUrl": "https://kodus-api.yourcompany.com",
  "teamKey": "kodus_xxxxx",
  "cfAccessClientId": "your-client-id.access",
  "cfAccessClientSecret": "your-client-secret"
}

The CLI sends CF-Access-Client-Id and CF-Access-Client-Secret headers on every API request when configured. Priority: env vars > config file.

Config File Reference

The CLI stores configuration in ~/.kodus/config.json:

{
  "apiUrl": "https://kodus-api.yourcompany.com",
  "teamKey": "kodus_xxxxx",
  "teamName": "Engineering",
  "organizationName": "Acme Corp",
  "cfAccessClientId": "your-client-id.access",
  "cfAccessClientSecret": "your-client-secret"
}

Field	Required	Description
`apiUrl`	No	Your self-hosted API URL. Overridden by `KODUS_API_URL` env var.
`teamKey`	No	Team API key (starts with `kodus_`). Overridden by `KODUS_TEAM_KEY` env var.
`teamName`	No	Display name for the team.
`organizationName`	No	Display name for the organization.
`cfAccessClientId`	No	Cloudflare Access client ID. Overridden by `CF_ACCESS_CLIENT_ID` env var.
`cfAccessClientSecret`	No	Cloudflare Access client secret. Overridden by `CF_ACCESS_CLIENT_SECRET` env var.

The config file is created with 0600 permissions (owner read/write only). The directory ~/.kodus/ is created with 0700 permissions.

Environment Variables Summary

Variable	Description
`KODUS_API_URL`	Self-hosted API endpoint (HTTPS required, except localhost)
`KODUS_TEAM_KEY`	Team key for shared access
`KODUS_TOKEN`	CI/CD token for pipelines
`CF_ACCESS_CLIENT_ID`	Cloudflare Access client ID
`CF_ACCESS_CLIENT_SECRET`	Cloudflare Access client secret
`KODUS_VERBOSE`	Set to `true` to see the resolved API URL and request details

CI/CD Integration

For self-hosted instances in CI/CD pipelines, set the API URL and authentication as environment variables:

GitHub Actions
GitLab CI
Generic

- name: Kodus Review
  env:
    KODUS_API_URL: ${{ secrets.KODUS_API_URL }}
    KODUS_TEAM_KEY: ${{ secrets.KODUS_TEAM_KEY }}
  run: npx @kodus/cli review --format json --fail-on error

kodus-review:
  script:
    - npx @kodus/cli review --format json --fail-on error
  variables:
    KODUS_API_URL: $KODUS_API_URL
    KODUS_TEAM_KEY: $KODUS_TEAM_KEY

export KODUS_API_URL=https://kodus-api.yourcompany.com
export KODUS_TEAM_KEY=kodus_xxxxx
npx @kodus/cli review --format json --fail-on error

Use --fail-on error or --fail-on critical to fail the pipeline when issues above a severity threshold are found.

Distributing to Your Team

To onboard your team in one command, combine the API URL with the skill installer:

KODUS_API_URL=https://kodus-api.yourcompany.com \
  curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx

This installs the CLI, configures the team key, and deploys review skills to detected AI agents (Claude Code, Cursor, Windsurf) — all pointing to your self-hosted instance.

Troubleshooting

Security Error: API URL must use HTTPS protocol

The CLI requires HTTPS for all non-localhost URLs. Make sure your self-hosted instance has a valid TLS certificate. If you’re testing locally, use http://localhost:<port> instead.

Connection refused or timeout

Verify the URL is reachable: curl -I https://kodus-api.yourcompany.com
Check if a firewall or VPN is blocking the connection
If behind Cloudflare Access, ensure CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET are set
Use --verbose to see the exact URL being used

Authentication failed (401)

Run kodus auth status to check your current auth state
If using a team key, verify it’s valid on your self-hosted dashboard
If using personal login, tokens expire after 1 hour — the CLI auto-refreshes, but you may need to re-login if the refresh token is also expired
Make sure KODUS_API_URL points to the correct instance

API returned invalid response (expected JSON, got HTML)

This usually means the URL is hitting a reverse proxy, load balancer, or Cloudflare Access page instead of the actual API. Check:

The URL path is correct (no trailing /api or similar)
Cloudflare Access credentials are configured if applicable
The reverse proxy is forwarding requests correctly

Device limit reached

Your self-hosted instance may enforce device limits per organization. Contact your admin to increase the limit or remove old devices from the dashboard.

Getting Started

Billing & Licenses

AI Code Review

CLI

Cockpit

Kody Issues

Organization

Security

Troubleshooting

Self-Hosted Setup

Connect to Your Instance

Cloudflare Access (Zero Trust)

Config File Reference

Environment Variables Summary

CI/CD Integration

Distributing to Your Team

Troubleshooting

​Connect to Your Instance

​Cloudflare Access (Zero Trust)

​Config File Reference

​Environment Variables Summary

​CI/CD Integration

​Distributing to Your Team

​Troubleshooting

Connect to Your Instance

Cloudflare Access (Zero Trust)

Config File Reference

Environment Variables Summary

CI/CD Integration

Distributing to Your Team

Troubleshooting