Instance management

Server commands

The konduktor-server binary manages the backend:

konduktor-server init                              # First-time setup (credentials + database)
konduktor-server start                             # Start server (127.0.0.1:8080)
konduktor-server start --host 0.0.0.0 --port 9090  # Custom host/port
konduktor-server upgrade                           # Run database migrations manually
konduktor-server configure-github-app              # Set up GitHub App integration

Data directory

All Konduktor data lives under ~/.konduktor/ by default:

Path	Purpose
`~/.konduktor/konduktor.db`	SQLite database
`~/.konduktor/credentials`	Server auth credentials
`~/.konduktor/server.log`	Server log
`~/.konduktor/github-app.json`	GitHub App config (if configured)
`~/.konduktor/github-app.pem`	GitHub App private key (if configured)
`~/.konduktor/cli.json`	CLI authentication token
`~/.konduktor/workspaces/`	Cloned workspace repositories
`~/.konduktor/workspaces/<workspace>/`	Individual workspace directory
`~/.konduktor/workspaces/<workspace>/sessions/`	Session JSONL log files

Override the data directory with the KONDUKTOR_DIR environment variable:

export KONDUKTOR_DIR=/opt/konduktor/data
konduktor-server start

Environment variables

Variable	Default	Purpose
`KONDUKTOR_DIR`	`~/.konduktor`	Data directory path
`KONDUKTOR_EXTERNAL_URL`	(none)	Public URL for UI, allows for agents to create working links in external services (e.g. GitHub PR descriptions)
`KONDUKTOR_UI_DIR`	(auto-detected)	Path to the built UI `dist/` directory

Running as a systemd service (Linux)

The one-liner install script creates a systemd unit at /etc/systemd/system/konduktor.service. Common operations:

sudo systemctl status konduktor      # Check status
sudo systemctl start konduktor       # Start
sudo systemctl stop konduktor        # Stop
sudo systemctl restart konduktor     # Restart
sudo systemctl enable konduktor      # Enable on boot
sudo systemctl disable konduktor     # Disable on boot
sudo journalctl -u konduktor -f      # Tail logs

The service is configured with:

Auto-restart on failure (5-second delay)
Read-only filesystem with write access only to ~/.konduktor
Process isolation (NoNewPrivileges=true)

Running on macOS

macOS doesn’t use systemd. Start the server manually:

konduktor-server start

Reverse proxy (nginx)

The install script optionally configures nginx. To set it up manually:

server {
    listen 80;
    server_name konduktor.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The Upgrade and Connection headers are required for SSE log streaming to work correctly. For HTTPS, use certbot:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d konduktor.example.com

Exposing for webhooks (development)

If your server isn’t publicly accessible and you want to use GitHub webhooks, you’ll need to use a tunneling service like Cloudflare Tunnel, ngrok, or zrok:

# Cloudflare Tunnel
cloudflared tunnel --url http://localhost:8080

# ngrok
ngrok http 8080

Then set your GitHub App’s webhook URL to the tunnel URL + /api/webhooks/github.

Database

Konduktor uses SQLite in WAL mode for concurrent read/write access. The database is at ~/.konduktor/konduktor.db. Migrations run automatically on server startup. To run them manually:

konduktor-server upgrade

Backups — since it’s a single SQLite file, copy it while the server is running (WAL mode makes this safe):

cp ~/.konduktor/konduktor.db ~/.konduktor/konduktor.db.backup

You might also want to backup the entire ~/.konduktor directory to ensure you have a complete backup of all your data.

cp -r ~/.konduktor ~/.konduktor.backup

Store these backups in a secure location.

Background processes

The server runs several background tasks:

Process	Interval	Purpose
Stuck detector	2 min	Kills agent sessions with no output for 2 hours
Orphan detector	10 min	Finds and kills processes not tracked by any session
Worktree cleaner	30 min	Removes orphaned git worktrees older than 24 hours
Conflict checker	1 min	Detects merge conflicts in active PR branches

Health check

konduktor status          # CLI health check
curl http://localhost:8080/api/health  # Direct HTTP check

Resource metrics

konduktor metrics         # CPU, memory, disk, and active session stats

Logging

Server logs go to both stderr (or systemd journal) and ~/.konduktor/server.log (10 MB, 3 rotated backups).

# Via CLI
konduktor logs server              # Recent server logs
konduktor logs server --limit 50   # Last 50 entries
konduktor logs runners             # Overview of runner logs by workspace
konduktor logs runner <workspace>  # Runner logs for a specific workspace

# Via systemd
sudo journalctl -u konduktor -f    # Tail live logs
sudo journalctl -u konduktor --since "1 hour ago"

Overview

Installation

Guides

Running Konduktor

CLI

Server commands

Data directory

Environment variables

Running as a systemd service (Linux)

Running on macOS

Reverse proxy (nginx)

Exposing for webhooks (development)

Database

Background processes

Health check

Resource metrics

Logging

​Server commands

​Data directory

​Environment variables

​Running as a systemd service (Linux)

​Running on macOS

​Reverse proxy (nginx)

​Exposing for webhooks (development)

​Database

​Background processes

​Health check

​Resource metrics

​Logging

Server commands

Data directory

Environment variables

Running as a systemd service (Linux)

Running on macOS

Reverse proxy (nginx)

Exposing for webhooks (development)

Database

Background processes

Health check

Resource metrics

Logging