Configuration

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

Configuration Priority

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

Server Configuration

Environment Variables

Variable	Description	Default
`KOD_PORT`	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`	API token for authentication	-
`KOD_ADMIN_TOKEN`	Admin token for first-time bootstrap	-
`KOD_ENCRYPTION_KEY`	Encryption key for secrets	-

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>            API token for authentication
  --admin-token <token>      Admin token for first-time setup
  --encryption-key <key>     Encryption key for secrets

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 serve

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

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

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:

Use a reverse proxy (Caddy or nginx) for automatic HTTPS
Set a strong admin token and generate scoped tokens for users and CI
Set an encryption key if you use secrets
Run as a systemd service for automatic restarts

systemd + Caddy
Docker

[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"
ExecStart=/usr/local/bin/kod serve
Restart=always

[Install]
WantedBy=multi-user.target

git.example.com {
  reverse_proxy localhost:3000
}

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 \
  node:24-slim \
  kod serve