Skip to main content

​
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:
PathPurpose
~/.konduktor/konduktor.dbSQLite database
~/.konduktor/credentialsServer auth credentials
~/.konduktor/server.logServer log
~/.konduktor/github-app.jsonGitHub App config (if configured)
~/.konduktor/github-app.pemGitHub App private key (if configured)
~/.konduktor/cli.jsonCLI 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

VariableDefaultPurpose
KONDUKTOR_DIR~/.konduktorData 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
For auto-start on login, create a launchd agent: 
mkdir -p ~/Library/LaunchAgents

cat > ~/Library/LaunchAgents/com.konduktor.server.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.konduktor.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<YOU>/.local/bin/konduktor-server</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<YOU>/.konduktor/server-stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/<YOU>/.konduktor/server-stderr.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.konduktor.server.plist
Replace /Users/<YOU> with your actual home directory path.

​
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:
ProcessIntervalPurpose
Stuck detector2 minKills agent sessions with no output for 2 hours
Orphan detector10 minFinds and kills processes not tracked by any session
Worktree cleaner30 minRemoves orphaned git worktrees older than 24 hours
Conflict checker1 minDetects 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"