> ## 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.

# Instance management

> Managing your Konduktor instance

## Server commands

The `konduktor-server` binary manages the backend:

```bash theme={null}
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:

```bash theme={null}
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](/installation/one-liner) creates a systemd unit at `/etc/systemd/system/konduktor.service`. Common operations:

```bash theme={null}
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:

```bash theme={null}
konduktor-server start
```

## Reverse proxy (nginx)

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

```nginx theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
konduktor-server upgrade
```

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

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
konduktor status          # CLI health check
curl http://localhost:8080/api/health  # Direct HTTP check
```

## Resource metrics

```bash theme={null}
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).

```bash theme={null}
# 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"
```