Configuration

Kod can be configured through CLI flags, environment variables, or a combination of both. CLI flags take the highest priority.

Configuration Priority

1. CLI flags (highest priority)
2. Environment variables
3. Config file (~/.kod/server.json)
4. Default values (lowest priority)

Server Configuration

Environment Variables

| Variable | Description | Default | |--------------------------|--------------------------------------|---------------------------| | KOD_PORT | HTTP port to listen on | 3000 | | KOD_DATA_DIR | Directory for database files | ~/.kod/data | | KOD_REPOS_DIR | Directory for Git repositories | ~/.kod/repos | | KOD_API_TOKEN | Legacy bootstrap token alias | - | | KOD_ADMIN_TOKEN | Admin token for first-time bootstrap | - | | KOD_ENCRYPTION_KEY | Encryption key for secrets | - | | KOD_SSH_ENABLED | Enable SSH Git server | true | | KOD_SSH_HOST | SSH listen host | 0.0.0.0 | | KOD_SSH_PORT | SSH listen port | 2222 | | KOD_SSH_HOST_KEY_PATH | SSH host private key path | ~/.kod/ssh_host_rsa_key | | KOD_SSH_ANONYMOUS_READ | Allow anonymous read-only SSH | false |

CLI Flags

kod serve [options]

Options:
  --port, -p <port>          Port to listen on (default: 3000)
  --data-dir <path>          Data directory for database
  --repos-dir <path>         Directory for Git repositories
  --token <token>            Legacy bootstrap token alias
  --admin-token <token>      Admin token for first-time setup
  --encryption-key <key>     Encryption key for secrets
  --ssh / --no-ssh           Enable or disable SSH Git access
  --ssh-host <host>          SSH listen host
  --ssh-port <port>          SSH listen port
  --ssh-host-key <path>      SSH host private key path
  --ssh-anonymous-read       Allow anonymous read-only SSH clone/fetch/list

Examples

# Minimal: start with admin token
KOD_ADMIN_TOKEN=kod_my_secret kod serve

# Custom port and directories
kod serve --port 8080 --data-dir /var/kod/data --repos-dir /var/kod/repos

# All via environment variables
KOD_PORT=8080 \
KOD_ADMIN_TOKEN=kod_my_secret \
KOD_ENCRYPTION_KEY=my-encryption-key \
KOD_SSH_PORT=2222 \
kod serve

SSH Git Access

Kod starts a built-in SSH Git server by default on port 2222. In production you can either expose that port directly or bind/forward port 22 to it.

# Add a collaborator and a username-linked token
kod repo my-app collaborator add alice
kod token create alice --username alice --permissions repo:read,repo:write

# Alice adds a public key with her token configured
kod keys add ~/.ssh/id_ed25519.pub

# Clone over SSH
git clone ssh://kod@git.example.com:2222/my-app.git

For public read-only mirrors, enable anonymous SSH reads:

KOD_SSH_ANONYMOUS_READ=true kod serve
git clone ssh://anonymous@git.example.com:2222/my-app.git

SSH also supports lightweight repository discovery:

ssh kod@git.example.com -p 2222 repos
ssh kod@git.example.com -p 2222 info my-app

Admin Token

The admin token bootstraps authentication on first server start. Without it, the server has no authentication and will log a warning.

There are two ways to provide it:

# Environment variable
KOD_ADMIN_TOKEN=kod_my_secret kod serve

# CLI flag
kod serve --admin-token kod_my_secret

First Start Only

The admin token is only used when no tokens exist in the database. If tokens already exist, the server logs a warning and the admin token is ignored. To reset, delete the data directory and restart.

After the server starts, use this token for all API and CLI operations. You can then create additional tokens with specific permissions:

kod token create ci-deploy --permissions repo:read,workflow:trigger

Encryption Key

The encryption key is required for the Secrets feature. It encrypts secret values at rest using AES-256-GCM.

# Generate a key
openssl rand -base64 32

# Provide it to the server
KOD_ENCRYPTION_KEY=your-generated-key kod serve

# Or via CLI flag
kod serve --encryption-key your-generated-key

Keep your encryption key safe

If you lose the encryption key, stored secrets cannot be decrypted. If secrets exist in the database but no encryption key is provided on startup, the server will refuse to start.

Client Configuration

The CLI client stores its configuration in ~/.kod/config.json:

{
  "serverUrl": "http://localhost:3000",
  "apiToken": "kod_your_token"
}

Set it up interactively:

kod init

Git Credential Helper

When installed globally (npm install -g kod), Kod includes a Git credential helper (git-credential-kod). Running kod init automatically configures Git to use it for the server host, so plain git clone, git push, and git pull authenticate without prompting.

To configure it manually:

git config --global credential.http://localhost:3000.helper kod

Or override per-command:

# Via flags
kod -t kod_my_token -s http://myserver:3000 repo list

# Via environment variables
KOD_API_TOKEN=kod_my_token KOD_SERVER_URL=http://myserver:3000 kod repo list

| Variable | Description | Default | |------------------|--------------------------------|-------------------------| | KOD_API_TOKEN | API token for authentication | - | | KOD_SERVER_URL | Server URL for client commands | http://localhost:3000 |

Production Deployment

For production, we recommend:

1. Use a reverse proxy (Caddy or nginx) for automatic HTTPS
2. Set a strong admin token and generate scoped tokens for users and CI
3. Set an encryption key if you use secrets
4. Run as a systemd service for automatic restarts
5. Expose SSH intentionally if you use SSH Git access (2222 by default, or forward/bind port 22)

systemd + Caddy

/etc/systemd/system/kod.service

[Unit]
Description=Kod Git Server
After=network.target

[Service]
Type=simple
User=kod
Environment="KOD_ADMIN_TOKEN=kod_your_secret"
Environment="KOD_ENCRYPTION_KEY=your-encryption-key"
Environment="KOD_DATA_DIR=/var/kod/data"
Environment="KOD_REPOS_DIR=/var/kod/repos"
Environment="KOD_SSH_PORT=2222"
ExecStart=/usr/local/bin/kod serve
Restart=always

[Install]
WantedBy=multi-user.target

/etc/caddy/Caddyfile

git.example.com {
  reverse_proxy localhost:3000
}

Docker

docker run -d \
  --name kod \
  --restart always \
  -e KOD_ADMIN_TOKEN=kod_your_secret \
  -e KOD_ENCRYPTION_KEY=your-encryption-key \
  -v kod-data:/root/.kod \
  -p 3000:3000 \
  -p 2222:2222 \
  node:24-slim \
  kod serve