Skip to main content

​
Prerequisites

  • git
  • Python 3.11+
  • Node.js 22+
  • pnpm (npm install -g pnpm)
  • uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
  • GitHub CLI installed and authenticated (cli.github.com)
  • Claude Code installed and authenticated (code.claude.com/docs/en/quickstart)

​
What GitHub user should I use?

We’ve seen Konduktor users use Konduktor in two ways:
  1. With their personal user
  2. With a separate dedicated bot user
It’s up to you which one you use. Using your personal user will give you proper commit attribution to commits made by Konduktor.

​
Token type and permissions

We recommend you authenticate into the gh CLI using a fine-grained token that you can create from the GitHub Personal Tokens settings page. No account permissions are necessary. At a minimum, you’ll need the following repository permissions on all repos or the repos you want Konduktor to be able to access:
  • Contents (read and write)
  • Pull requests (read and write)
You might also choose to give other permissions that can be useful:
  • Issues (if you want Konduktor to be able to read and action on issues)
  • Workflows (if you want Konduktor to be able to edit CI)
  • Pages (if you’re using Konduktor with GitHub Pages)
  • Actions (if you want Konduktor to be able to inspect Actions runs)
You can sync git credentials with your gh user by running gh auth setup-git.

​
Install

​
1. Clone

git clone https://github.com/yakkomajuri/konduktor-oss.git
cd konduktor-oss

​
2. Python backend

uv sync
uv tool install --force --from . konduktor
This installs the konduktor-server CLI that you can use to manage the Konduktor server and run updates. This is different from the konduktor CLI that is used on any machine you want to connect to Konduktor from.

​
3. CLI

cd cli
pnpm setup
cd ..
This installs the konduktor CLI that you can use on the machine you installed Konduktor on, and that’s also used by the Konduktor agents themselves internally.

​
4. UI

cd ui
pnpm install
pnpm run build
cd ..

​
5. Initialize server (first time only)

konduktor-server init

​
6. Start

konduktor-server start
The server runs on http://127.0.0.1:8080 by default. For production, put it behind a reverse proxy (nginx, Caddy, etc.) and get a TLS certificate for your domain. You’re also recommended to set this up as a systemd service or use Supervisor to keep the server running. See Instance Management for details.

​
Next steps

After installation, you should: Install the Konduktor CLI locally on your machine In case you’re running Konduktor on a remote machine, you’ll need to install the CLI on your local machine in order to execute commands against your Konduktor instance. 
npm install -g konduktor
This will allow you to do anything you can do with the Konduktor UI such as creating and running tasks, editing projects, setting up scheduled agents, managing the board, etc. And, not only will it be available to you, but also to your terminal coding agents, who can execute Konduktor actions for you. And I’ll tell you right now, this is the best way to do thigs like create a project from a feature spec. Verify it’s installed correctly and then login: 
konduktor -v
konduktor auth login
Create a workspace You can do this via the UI or using the CLI: 
konduktor workspaces add org/repo
Create and run a task Again, use the UI or run the following command from the CLI: 
konduktor tasks create --title "My first task" -w <workspace>
konduktor tasks run <task-id> -w <workspace> # using the task ID from the previous command