Get Started

Use this guide to run one agent on one local Git repository. Start with the built-in Worktree profile so the agent works in a separate checkout.

Quick path

1. Install and start Kandev.
2. Add a local repository and review its scripts and trust boundary.
3. Configure an agent profile and keep Worktree selected for the first task.
4. Start, inspect, test, and review the task before archiving or opening a pull request.

Prerequisites

• Git and filesystem access to the repository.
• Credentials for at least one supported coding-agent CLI. Kandev can run an advertised installer on the Kandev host, but it does not create the provider account or subscription.
• npm 7 or newer only for the npm/npx distribution.
• Docker only for Docker executor profiles. SSH and Sprites profiles have their own host or token requirements.

Kandev runs the selected agent with the access exposed by its executor, profile, environment, MCP policy, and credentials. Use a test repository and scoped credentials while learning the product.

Install and start

Choose one release channel:

# Homebrew on macOS or Linux
brew install kdlbs/kandev/kandev
kandev

# Scoop on Windows
scoop bucket add kandev https://github.com/kdlbs/scoop-kandev
scoop install kandev
kandev

# One-off npm launch
npx kandev@latest

# Global npm installation
npm install -g kandev@latest
kandev

Scoop installs the native runtime bundle, so Node.js is not required to install or start Kandev. It is still needed for the agent CLIs Kandev installs through its own interface.

Stable is the default and is selected by npm's latest tag. To test the current prerelease from main without changing a global installation, launch the package once from the npm-only nightly tag:

npx -y kandev@nightly

To replace a global Stable installation with Nightly, use:

npm install -g kandev@nightly
kandev

The global command replaces the installed kandev channel. Return to Stable with npm install -g kandev@latest.

Nightly builds may be unstable. They are best-effort daily snapshots, and a new version appears only when main has commits after the latest Stable release. Homebrew, Scoop, Desktop, and container installs have no Nightly channel.

The launcher selects the platform runtime, starts the Go backend and agent runtime, serves the web app, and opens its local URL. The preferred backend port is 38429; if it is unavailable, the launcher chooses another free port and prints the actual URL. Use kandev --headless (or KANDEV_NO_BROWSER=1) when a browser must not open.

By default, persistent state is under ~/.kandev, including the SQLite database, repository materializations, sessions, logs, and backups. KANDEV_HOME_DIR relocates that root. KANDEV_DATABASE_PATH overrides the database file and moves System snapshots to backups/ beside that file. Kandev creates its data directory with owner-only permissions and rejects symlinked components in that path, but file permissions do not replace host access controls. Kandev does not move snapshots from another directory automatically.

See the CLI reference for commands, port and logging flags, data paths, environment variables, and update behavior. Other supported entry points are the desktop app, service, and Docker deployment. Read Security and trust before making any installation remotely reachable.

Know what a fresh database contains

Kandev creates these records when no prior workspace or executor configuration exists:

• Default Workspace.
• Development, materialized from the built-in Kanban (simple) workflow template.
• System Local and Worktree executors, plus matching Local and Worktree executor profiles.
• A Local Docker executor configured with the platform's default Docker host. The record is created even when no usable Docker daemon is available; task launch still requires one.
• A disabled Sprites executor entry.

The first-run dialog scans supported agent CLIs, lets you inspect detected profiles, and introduces executors, workflows, and the command panel. Skip stores only a browser-local onboarding marker. Advancing/completing also saves any dirty agent-profile edits made in the dialog. Neither path creates another workspace. The dialog warns that default agent profiles can have Auto Approve enabled. Inspect every profile before assigning trusted code or credentials.

Find a setting

Open Settings and use Search settings at the top of its navigation tree. Search results are grouped by area; selecting a specific control opens its owning page, scrolls it into view, focuses it, and briefly highlights it without changing the saved value. The same search is available in the Settings menu on phones.

From anywhere, press Cmd/Ctrl+K and begin typing a setting name or familiar alias. Individual settings appear only after typing, while Go to Settings remains in the command menu at rest. Discovery searches setting names and curated aliases, never saved values, secrets, paths, or other configuration content.

Switch workspace

The workspace picker sits in the sidebar header, next to the Kandev brand. It lists every workspace with a Kanban or Office badge and ends with the workspace-creation actions.

From anywhere, press Cmd/Ctrl+E to open it with the keyboard: focus lands inside the menu, so arrow keys move between workspaces and Enter switches to the highlighted one. If the sidebar is collapsed, the shortcut expands it first. Rebind it under Settings > General > Keyboard Shortcuts (Open Workspace Picker) if it clashes with a browser or window-manager binding.

The shortcut does nothing on narrow windows and phones, where the sidebar is hidden. Switch workspace there from the menu sheet instead.

Add a local repository

1. Open Settings > Workspaces > Default Workspace > Repositories. If you created or renamed the workspace, choose that workspace instead.
2. Select Add Local Repository.
3. Choose a discovered repository, or enter an absolute path and select Validate. The backend accepts any existing Git repository the Kandev process can access. Configured discovery roots bound automatic scans; they do not restrict an explicit path.
4. Select Use Repository. This opens an unsaved repository card.
5. Review the repository name, worktree branch template, pull behavior, setup/cleanup/dev scripts, copied files, and custom commands. Then select Save changes.

New local repository records default to:

• source type local;
• legacy worktree branch prefix feature/;
• worktree branch template feature/{title}-{suffix};
• pull-before-worktree enabled;
• empty setup, cleanup, dev, copied-file, and custom-script configuration.

Scripts execute in agent workspaces and therefore belong to the trust boundary. Do not add an unreviewed command or copy pattern. Repository deletion is irreversible in the UI and is blocked while an active task session still references the repository.

Repositories saved by an older Kandev version may still contain a path spelling with symbolic-link components. If branch operations report that such a saved path resolves to a different location after upgrading, edit and save the repository path again to record its current canonical location. Kandev does not silently accept the new resolution because that would also accept a saved path whose symbolic-link target was changed after registration.

Remote repository and issue/PR URLs are not added from this settings page. Use the Remote tab in New Task to search configured GitHub, GitLab, and Azure DevOps repositories, or paste a supported provider URL. See Integrations and Tasks and workflows.

Configure an agent profile

1. Open Settings > Agents.
2. Select Rescan if an installed CLI is missing. An available agent appears with its detected installation and authentication state.
3. If necessary, select Install. Kandev runs that agent's advertised install script on the Kandev host and shows live output. You can instead install it yourself and rescan.
4. Complete the provider's authentication flow. Some agents expose a dedicated login terminal; others use their own CLI outside Kandev.
5. Open the agent and its profile. Verify the selected model and mode, permission switches, CLI flags, environment variables, MCP configuration, and CLI-passthrough setting. Save changes.

Detected capabilities come from the installed CLI and can change after an agent upgrade or login. A model or mode shown in documentation is not guaranteed for every account. If no built-in adapter fits, Add TUI Agent creates a passthrough integration; passthrough has a different resume, usage, and MCP contract from an ACP-capable agent.

For the first task on an existing repository, keep the seeded Worktree executor profile. It creates a separate Git checkout so concurrent Kandev tasks do not edit the same working tree. A worktree is Git isolation, not operating-system isolation. Choose Local only when direct edits in the selected checkout are intentional. A repository initialized from New Task already has one empty initial commit and no project files, and Kandev selects a direct Local profile for that flow. See Agents and profiles and Executors before using Docker, SSH, Sprites, custom scripts, or shared infrastructure.

Create and start the first task

1. Select New Task from the sidebar or task board.
2. Enter a specific title and a description with the expected outcome, constraints, and validation. A non-empty description enables the normal start and create-only actions.
3. Under Repo, select the workspace repository and base branch. To start a new project, open the repository selector, choose Create new repository, enter one folder name, and select its parent folder. Kandev creates an empty main repository with one empty initial commit and no project files. Select None only for work that genuinely needs a plain workspace directory.
4. Choose the Development workflow and an agent profile. For an existing repository, choose the Worktree executor profile. For a newly initialized repository, keep the Local profile that Kandev selects automatically. Kandev remembers compatible recent choices, so re-check them after changing repository, agent, or trust boundary.
5. Select Start task. Its menu also offers Start task in plan mode and Create without starting agent. On an empty description, the primary action is Start Plan Mode.

Starting creates the task and its initial session. Workflow step configuration determines whether entry actions or later transitions start another session, inject a prompt, or stop at a human gate. With a structured ACP profile, create-only prepares the session/workspace without starting an agent turn. A passthrough/TUI profile is the exception: the backend upgrades prepare-only to a full launch because the native PTY must exist.

Start from an empty remote

When the selected repository's remote has no refs, Kandev creates an empty local baseline during task preparation so the agent can use the normal Worktree executor. It adds no project files and does not publish the baseline during launch, resume, or worktree recovery.

After the agent creates and commits work, open Changes and choose Push or Create pull request. Kandev publishes the selected base branch before the task branch and uses the task runtime's Git credentials. Read or clone access alone does not authorize this first publication. Provider change-request creation starts only after both branches are available on the remote.

If another actor initializes the remote first, Kandev stops without replacing that history. Reconcile the remote with the task branch before retrying. If the base was published but the task branch was not, retry Push; Kandev keeps the local task branch. The same flow is available from the touch-sized Changes menu on phones.

The dialog also supports multiple repositories, remote GitHub rows, and a single-repository Fork a new branch option when the Local executor is selected. Important boundaries:

• Multi-repository tasks require the Worktree executor in the current task-create path.
• Creating an empty repository is available only for a single repository row and switches the task to a direct Local profile.
• No-repository tasks cannot use the Worktree executor.
• The local fork option is off by default and requires explicit consent before Kandev discards dirty source-checkout changes.
• Agent and executor choices can be disabled when their remote credential requirements are incompatible.

Supervise and finish the task

1. Watch chat and tool activity. Answer clarification or permission requests instead of assuming a stalled process is finished.
2. Inspect terminal output, files, preview, and Changes while the session runs.
3. Review the cumulative diff and any walkthrough. Add anchored review comments or another prompt when corrections are needed.
4. Run the repository's required checks. Agent completion does not prove that tests passed.
5. Inspect commits and branch state. Create or associate a pull request only after provider credentials and the target base branch are correct.
6. Move the task through the workflow's human review gate. Archive it only after deciding what should happen to its branch, worktree, and external issue or pull request.

See Sessions and review for the workbench and Tasks and workflows for transitions, plans, workflow automation, and the current document and label limitations.

Credentials and security boundaries

• Prefer Kandev secret references and provider-native login over plaintext environment values. Scope tokens to the required repositories and API operations.
• Auto Approve, permission-skipping flags, and unrestricted passthrough remove human gates inside the agent CLI. They are security decisions.
• Local and worktree sessions run on the Kandev host. Worktree separation does not limit process, filesystem, network, or credential access.
• Containers and remote executors change the boundary, but their mounted files, copied credentials, environment, daemon/socket access, and prepare scripts can reintroduce host or provider access.
• Managed GitHub task access (the default) uses task/repository-bound broker leases from the workspace automation connection. GitHub App tokens are minted for the redeemed repository; PAT and named-CLI bearer tokens retain all provider-granted scopes once delivered to the trusted agent subprocess. Personal tokens and the App private key never enter executors. Choose Inherit executor Git credentials in the workspace GitHub settings only when task Git and gh should use host-visible credentials for Local/Worktree or intentionally configured credentials for remote executors.
• A profile-supplied GITHUB_TOKEN or GH_TOKEN is an explicit unmanaged override and bypasses workspace broker selection. Ambient backend tokens and the host-active gh account are used only by migration-only Legacy shared workspace connections.
• Repository, executor, and task action scripts are executable configuration. Review them like code.
• The web app, HTTP API, WebSocket, and external MCP routes currently have no Kandev user-login boundary. Treat anyone who can reach the backend as an operator; keep the whole origin on loopback or a trusted network, or put it behind an authenticated TLS proxy.

Use the Security and trust guide to choose a local, remote, shared-team, or unattended-automation boundary and to review the deployment checklist.

Troubleshoot a task that will not start

Check in this order:

1. Settings > System > Status for reported health issues, disk usage, and the running version.
2. Settings > Agents for CLI availability, probe errors, login state, profile model/mode, and permission configuration.
3. The repository card and branch. Run git status and git fetch as the same operating-system user that runs Kandev.
4. Settings > Executors for a disabled or incompatible profile and for Docker, SSH, Sprites, image, host, or prepare-script failures.
5. The task's session error and terminal output, then Settings > System > Logs for backend/runtime details.
6. Available disk space. Repositories, worktrees, session state, logs, and backups all consume the Kandev data root.

Common corrections:

• If an agent is absent after installation, run Rescan and inspect the host terminal's PATH.
• If a profile has no usable model or mode, authenticate the CLI, rescan, and reopen the profile. Capability probing can heal selections that an upgraded CLI removed.
• If repository validation fails, use an absolute path to an existing, accessible Git working tree. Discovery roots control automatic scans only; they do not restrict an explicit path.
• If a worktree cannot be prepared, resolve dirty/conflicting branch state, remote authentication, pull errors, setup-script failures, and disk exhaustion before retrying. If another actor initialized an empty remote, reconcile that history with the local task branch first.
• If the browser did not open, use the URL printed by the launcher or start with --headless; do not assume port 38429 when the launcher selected a fallback.

For backup, update, log, database, and recovery details, see Operations. For release-specific disagreement, record the version from Settings > System > About and compare it with the matching GitHub tag.