Documentation Index
Fetch the complete documentation index at: https://konduktor-docs.yakko.dev/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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
- 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:
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";
}
}
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
/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:
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
~/.konduktor directory to ensure you have a complete backup of all your data.
cp -r ~/.konduktor ~/.konduktor.backup
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"
