docs: simplify public documentation for scanning (#2139)
This commit is contained in:
Carlos Florêncio
@@ -42,7 +42,12 @@ Skip public docs when the change is:
|
||||
4. If no public docs exist but the behavior is user-facing, add or propose the smallest useful public page/section.
|
||||
When adding a page, include `title` and `description` frontmatter and list its page slug or path without the `.md` extension in `docs/public/meta.json` exactly once, for example `cli`. See `docs/public/README.md`.
|
||||
5. If the change only updates implementation intent or architectural history, update specs/plans/ADRs instead.
|
||||
6. Keep public docs task-oriented: prerequisites, commands, expected result, troubleshooting, and links to reference.
|
||||
6. Keep public docs task-oriented and scan-friendly:
|
||||
- Start with the common path, expected result, and only the prerequisites it needs.
|
||||
- Use short paragraphs (one idea, normally three sentences or fewer) and bullets for choices, limits, and consequences.
|
||||
- Prefer a link to the page that owns a detailed contract over repeating it.
|
||||
- Use native `<details>` / `<summary>` disclosures for non-essential edge cases, exhaustive option lists, and advanced configuration. Keep required steps, security warnings, destructive effects, and eligibility limits visible.
|
||||
- Use tables only for genuine comparisons, not narrative text.
|
||||
7. Preserve internal links inside `docs/public/**` where possible. Link to source-only raw docs only when the raw note is intentionally not published.
|
||||
8. Note docs impact in the PR body.
|
||||
|
||||
|
||||
+34
-1
@@ -9,6 +9,39 @@ The published docs have two audiences:
|
||||
|
||||
Keep implementation detail in contributor pages. A user guide should explain the supported behavior and link here when internal context is useful.
|
||||
|
||||
## Write for scanning
|
||||
|
||||
Readers should be able to complete the common path without reading a full
|
||||
reference. Prefer this structure:
|
||||
|
||||
1. Open with one sentence that says who the page is for and what it enables.
|
||||
2. Put the common path in a short numbered list near the top.
|
||||
3. Use bullets for choices, limits, prerequisites, and consequences.
|
||||
4. Keep paragraphs to one idea and normally no more than three sentences.
|
||||
5. Link to the owning reference instead of repeating its detail.
|
||||
|
||||
Use a table only when readers must compare several options. Do not turn a
|
||||
page into a complete inventory of UI labels, implementation behavior, or
|
||||
exception cases.
|
||||
|
||||
Put useful but non-essential detail behind a native disclosure. Good candidates
|
||||
include exhaustive provider differences, compatibility notes, rare recovery
|
||||
paths, and background implementation behavior. Do not hide the required steps,
|
||||
security warnings, destructive effects, or a limitation that changes whether a
|
||||
feature can be used.
|
||||
|
||||
```md
|
||||
<details>
|
||||
<summary>Advanced configuration and edge cases</summary>
|
||||
|
||||
Keep the detail concise, and link to the full reference when it grows.
|
||||
</details>
|
||||
```
|
||||
|
||||
Reference pages may be longer, but should still start with the most common
|
||||
configuration or request and progressively disclose the rest. Delete repeated
|
||||
explanations; one page should own each detailed contract.
|
||||
|
||||
## Update an existing page
|
||||
|
||||
Edit the Markdown source and verify every command, setting, label, default, platform claim, and screenshot against current source or tests. Preserve the filename when possible: it is the public slug.
|
||||
@@ -62,7 +95,7 @@ Place the indicator immediately after a descriptive heading that names the exper
|
||||
4. Add the slug, without `.md`, exactly once to `docs/public/meta.json` under the correct audience heading. Its position controls sidebar order. `README.md` is the maintenance guide and is not a published page.
|
||||
5. Add the page to at least one area in `docs/public/coverage.json`, with current implementation and test evidence.
|
||||
6. Link the page from the relevant overview and neighboring guides.
|
||||
7. Include prerequisites, a concrete workflow, exact configuration, failure modes or limits, and related pages where applicable.
|
||||
7. Include a short common path, then only the prerequisites, exact configuration, limits, and related pages needed for that path. Put secondary detail in a disclosure or the owning reference page.
|
||||
|
||||
The validator rejects missing frontmatter, pages absent from navigation or coverage, duplicate or unknown navigation entries, broken local files or heading fragments, missing assets, and site-root links.
|
||||
|
||||
|
||||
@@ -15,6 +15,15 @@ Choose the smallest integration that matches the CLI:
|
||||
|
||||
ACP, REST, and MCP are different boundaries. ACP is the only structured agent protocol accepted by the current agentctl adapter factory. REST/WebSocket control agentctl and Kandev. MCP supplies tools to an agent; it is not a runtime adapter.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Use **Add TUI Agent** for a local terminal-only CLI.
|
||||
2. Add a built-in `TUIAgent` only when every Kandev install needs it.
|
||||
3. Use a full ACP integration for structured chat, tools, models, modes, or resume.
|
||||
4. Validate the path you chose:
|
||||
- local TUI: installation discovery and exact command-token construction;
|
||||
- built-in or ACP: declared permissions, credentials, resume, and MCP delivery.
|
||||
|
||||
## Register a local TUI agent
|
||||
|
||||
Open **Settings → Agents**, choose **Add TUI Agent**, and provide:
|
||||
|
||||
@@ -9,7 +9,13 @@ Agents running in separate Kandev tasks can talk to each other directly. One age
|
||||
|
||||
Communication works across all relationship types — parent to child, child to parent, sibling to sibling, and tasks in entirely different workspaces or workflows ("projects"). The only requirement is that each agent knows the other task's full UUID.
|
||||
|
||||
The examples below use canonical MCP protocol names ending in `_kandev`. An agent client may show a server-qualified display or registry alias, such as `mcp__kandev__message_task_kandev`; the prefix is client-specific, so use the form exposed by the active client rather than treating the qualified form as universal.
|
||||
The examples below use canonical MCP protocol names ending in `_kandev`. An agent client may show a server-qualified alias; use the form exposed by that client.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Discover the peer task's full UUID.
|
||||
2. Send a bounded request with the expected result and reply target.
|
||||
3. Read the reply, confirm the contract, then implement and test.
|
||||
|
||||
## Discovering task IDs
|
||||
|
||||
@@ -83,6 +89,9 @@ There is no persistent channel or shared socket between tasks. Each `message_tas
|
||||
|
||||
Pagination and filtering are available via `limit`, `before`, `after`, `sort`, and `message_types` parameters. `message_types=["message"]` returns every regular chat/prompt row — the same `message` type covers ordinary user turns and cross-task deliveries alike, so this filter alone does not isolate coordination traffic. To identify a message that arrived via `message_task_kandev`, check the returned message's `metadata.sender_task_id` (and `sender_task_title`): messages sent within the same task have no `sender_task_id`. Include `"tool_call"` in `message_types` to see tool outputs too.
|
||||
|
||||
<details>
|
||||
<summary>Worked example: API contract negotiation</summary>
|
||||
|
||||
## Worked example — API contract negotiation
|
||||
|
||||
Backend Task A and Frontend Task B need to agree on an API contract before they both start implementing. Neither task knows what the other needs; they resolve it through a short negotiation.
|
||||
@@ -163,6 +172,8 @@ get_task_conversation_kandev(
|
||||
|
||||
Task B processes each incoming message as a normal turn. When it receives Agent A's proposal, it reads the current frontend component that consumes the API, identifies the missing field, and sends back a specific counter-proposal. When the agreement arrives, it proceeds to implement its API client with the agreed shape.
|
||||
|
||||
</details>
|
||||
|
||||
## Good practices
|
||||
|
||||
**Be self-contained.** Each message should include enough context for the receiving agent to act without looking up prior conversation history — task ID, repo, branch, current status, and what you expect in return.
|
||||
|
||||
@@ -5,9 +5,16 @@ description: "Install agent CLIs and create profiles for models, modes, flags, s
|
||||
|
||||
# Agents and Profiles
|
||||
|
||||
An **agent** is Kandev's integration with a coding-agent CLI. A **profile** is a reusable launch configuration for that agent. Profiles let the same installed CLI run with different models, modes, credentials, flags, or trust levels.
|
||||
An **agent** is Kandev's integration with a coding-agent CLI. A **profile** is its reusable launch configuration. Create separate profiles when model, credentials, or permissions need different trust boundaries.
|
||||
|
||||
Agent authentication is separate from repository credentials and from credentials saved under an integration. Installing a CLI does not sign it in, and connecting GitHub does not let an agent call its model provider.
|
||||
Agent authentication is separate from repository and integration credentials.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Rescan or install the agent on the host running Kandev.
|
||||
2. Authenticate it as the same operating-system user.
|
||||
3. Create a profile and verify model, mode, permissions, environment, and executor compatibility.
|
||||
4. Use the advanced sections only when you need passthrough, MCP, or custom launch behavior.
|
||||
|
||||
## Install or detect an agent
|
||||
|
||||
@@ -26,42 +33,24 @@ The status shown on this page is authoritative for the current host. A CLI that
|
||||
|
||||
### Update a managed agent runtime
|
||||
|
||||
Installed Claude, Codex, OpenCode, Copilot, and Gemini cards provide an update
|
||||
icon. Kandev invokes these managed npm runtimes without an
|
||||
exact version or `latest` tag during ordinary launches, so npm can reuse its
|
||||
best-effort execution cache. The version reported by the agent is the
|
||||
authoritative current version; Kandev does not infer it from the application
|
||||
release.
|
||||
The update icon is available on managed Claude, Codex, OpenCode, Copilot, and
|
||||
Gemini agent cards. It updates the runtime on the Kandev host.
|
||||
|
||||
Select the update icon to deliberately check npm and refresh the managed
|
||||
runtime on the Kandev host. Before anything changes, the update dialog shows
|
||||
the current and upstream target versions, the exact command Kandev will run,
|
||||
and how the update affects sessions. When the reported current and target
|
||||
versions match, the dialog shows the version once as **Up to date** and keeps
|
||||
**Approve update** disabled. After a successful preview provides both current
|
||||
and target versions and they differ, select **Approve update** to start it;
|
||||
the action stays disabled when either version is missing, the preview is
|
||||
loading, or the preview has an error.
|
||||
The dialog streams progress and stdout/stderr until the update finishes; those
|
||||
details do not appear on the agent card and are cleared when you restart the
|
||||
page. After the package update, Kandev automatically starts a fresh ACP
|
||||
capability probe. A successful probe replaces the advertised models, modes,
|
||||
1. Select the update icon.
|
||||
2. Review the current version, target version, and command.
|
||||
3. Select **Approve update**. If the update fails, select **Retry update**.
|
||||
4. Wait for the capability refresh to finish.
|
||||
|
||||
Kandev disables approval when the versions already match or the version check
|
||||
is incomplete. A successful refresh updates the advertised models, modes,
|
||||
configuration options, commands, and runtime version without a page reload.
|
||||
|
||||
The action changes later host probes and sessions only. It does not restart an
|
||||
active session, update a separately configured passthrough or authentication
|
||||
helper, or update remote executors and running containers. Those environments
|
||||
resolve their own unversioned runtime when they launch.
|
||||
- Active sessions keep running; later probes and launches use the refreshed runtime.
|
||||
- Passthrough agents, authentication helpers, remote executors, and running containers are unchanged.
|
||||
- If the update or refresh fails, Kandev keeps the previous capability catalogue and shows the error. Authenticate the host agent, then retry.
|
||||
|
||||
If registry lookup or package execution fails, Kandev keeps the previous
|
||||
capability catalogue and shows the captured failure in the dialog. If the
|
||||
package updates but the follow-up probe requires authentication, the dialog
|
||||
reports the update plus the refresh error; authenticate the host agent and
|
||||
refresh again. Update job history is short-lived and does not survive a backend
|
||||
restart, and npm cache contents are not a durable Kandev installation record.
|
||||
When the first managed package update fails, Kandev removes only that
|
||||
package's extracted npm execution tree and retries the same update once; a
|
||||
repair or second failure is reported as failed and does not retry indefinitely.
|
||||
<details>
|
||||
<summary>Add a custom terminal agent</summary>
|
||||
|
||||
### Add a custom terminal agent
|
||||
|
||||
@@ -69,6 +58,8 @@ Use **Settings > Agents > Add TUI Agent** for a CLI that Kandev does not registe
|
||||
|
||||
That parser is not a shell and is not quote-aware: quotes and backslashes do not preserve a path or model containing spaces as one argument. Custom TUI agents always use terminal passthrough. They do not gain ACP features such as structured permission prompts, model discovery, modes, or session configuration merely by being added. Test the exact resulting argument split before assigning it to work.
|
||||
|
||||
</details>
|
||||
|
||||
## Create and configure a profile
|
||||
|
||||
Select an agent, create a profile, then open **Settings > Agents > _Agent_ > _Profile_**. The page shows the resolved command preview and only the settings supported by that agent.
|
||||
@@ -92,6 +83,9 @@ Model, mode, command, and configuration choices are probed from the locally inst
|
||||
|
||||
Use the profile refresh control after installing, authenticating, or upgrading an agent. A manual refresh updates both the advertised models, modes, and commands and the visible capability status, so an old failure banner does not remain authoritative after the local CLI recovers.
|
||||
|
||||
<details>
|
||||
<summary>Office agent quota and provider usage</summary>
|
||||
|
||||
### Monitor Office agent quota
|
||||
|
||||
> [!EXPERIMENTAL]
|
||||
@@ -120,6 +114,11 @@ signals, not a billing ledger or a guarantee that the next request will be
|
||||
accepted; provider availability, account policy, and concurrent usage still
|
||||
apply.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>CLI flags and ACP command prefixes</summary>
|
||||
|
||||
### CLI flags
|
||||
|
||||
Each flag entry has a raw value, description, enabled state, and an agent-specific default where applicable. Only enabled entries reach the process. Kandev tokenizes each raw value as command arguments: `--add-dir /shared` becomes two arguments.
|
||||
@@ -134,6 +133,8 @@ Some older profiles contain compatibility fields such as Auggie's `allow_indexin
|
||||
|
||||
The prefix must contain a nonempty first argv element that is not flag-like. Malformed quotes, a trailing escape, an empty launcher, or a prefix beginning with `-` is rejected when you save or preview it. If an older persisted profile contains an invalid prefix, Kandev fails the launch rather than silently running the agent without its configured launcher. Check the command preview after changing a prefix.
|
||||
|
||||
</details>
|
||||
|
||||
## Environment variables and secrets
|
||||
|
||||
Create reusable secrets at **Settings > Secrets** (`/settings/general/secrets`), then select a secret reference in a profile environment entry. Secret names are 1–100 characters and values are 1–10,000 characters. Editing a secret with a blank value keeps the saved value.
|
||||
@@ -167,6 +168,11 @@ ACP sessions can expose typed messages, tool updates, permission requests, model
|
||||
|
||||
Passthrough preserves the CLI's native PTY interface. It is useful when the native terminal has features that ACP does not expose, but Kandev cannot manufacture structured capabilities that are absent. Custom TUI profiles are locked to passthrough. Profile-specific MCP injection also varies by CLI; verify the command preview and the MCP section before depending on it.
|
||||
|
||||
> **MCP credential exposure:** MCP headers and environment values are stored in profile configuration. Codex may place them in process arguments, and Cursor or Pi may leave them in project files after teardown. Use short-lived, narrowly scoped credentials and review persisted files.
|
||||
|
||||
<details>
|
||||
<summary>Configure external MCP servers</summary>
|
||||
|
||||
## Add external MCP servers to a profile
|
||||
|
||||
When an agent advertises MCP support, open its profile's **MCP** section. The editor accepts either a servers map or an object containing `mcpServers`.
|
||||
@@ -187,6 +193,8 @@ Passthrough injection adds CLI-specific exposure. Codex encodes MCP environment
|
||||
|
||||
Kandev does not validate a server-name syntax centrally, so blank or unusual names can fail or be transformed differently by each CLI. A missing command/URL, unsupported or denied transport, or server-name policy denial skips that server with a warning. Configuring `shared` mode for a stdio server is different: it aborts profile MCP resolution with an error. Review launch/session logs when an expected tool is missing.
|
||||
|
||||
</details>
|
||||
|
||||
## Delete profiles and custom agents
|
||||
|
||||
Deleting a profile is irreversible. Kandev checks references before deletion:
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Understand Kandev's process, code, runtime, persistence, event, pr
|
||||
|
||||
Kandev is a server-first development workbench. A Go backend owns durable product state and orchestration. The browser UI is a Vite-built React SPA. Agent processes run behind an `agentctl` sidecar in local, worktree, container, or remote task environments.
|
||||
|
||||
## Read this page in order
|
||||
|
||||
1. Start with the process diagram.
|
||||
2. Follow backend ownership and task runtime to find the code that owns a behavior.
|
||||
3. Use the protocol and event sections for cross-process contracts.
|
||||
4. Check trust boundaries before changing credentials, executors, providers, or MCP.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI["Browser or Tauri window"] -->|HTTP + WebSocket| BE["Go backend"]
|
||||
|
||||
@@ -9,6 +9,14 @@ Kandev ships as a single-user local tool with authentication **disabled** — no
|
||||
|
||||
Authentication is a **runtime feature toggle** — the same system as the other feature flags — so there is no separate "Authentication" configuration page.
|
||||
|
||||
## Quick checklist
|
||||
|
||||
1. Keep authentication off only for a single-user laptop bound to loopback or another private listener.
|
||||
2. For any server reachable by other users or networks, enable **Authentication & users** and restart.
|
||||
3. Create the first admin immediately after setup mode appears.
|
||||
4. Use personal access tokens for scripts and external MCP clients.
|
||||
5. Keep TLS, filesystem permissions, and agent credentials as separate security boundaries.
|
||||
|
||||
## What changes when authentication is on
|
||||
|
||||
- Everyone signs in with email + password. Browser sessions last 30 days (sliding) and can be revoked from `Settings > Account`. The signed-in user is shown in the bottom-left of the sidebar, with a log-out menu.
|
||||
|
||||
@@ -20,6 +20,15 @@ Use workflow events for predictable transitions on existing work. Use a workspac
|
||||
|
||||
Across Kandev's task, configuration, external, and Office MCP modes, each tool call is validated against that mode's live `tools/list` schema before its handler runs. Missing required fields, wrong types, declared constraint violations, and unknown top-level fields return a tool error without performing the requested action. Nested configuration maps still accept arbitrary keys when their schema defines them as open.
|
||||
|
||||
## Quick path
|
||||
|
||||
- Use a **workflow event** for predictable transitions on existing tasks.
|
||||
- Use a **workspace automation** when a schedule or external signal should create work.
|
||||
- Use **task MCP** for tools inside an active agent session.
|
||||
- Use **profile MCP** to add servers to an agent profile.
|
||||
- Use **external MCP** to expose Kandev tools to third-party clients.
|
||||
- Treat credentials delivered through any MCP or executor profile as available to the receiving agent.
|
||||
|
||||
## Workflow events and human gates
|
||||
|
||||
Regular workflow entry actions can enable plan mode, reset agent context, or auto-start an agent; auto-start can use the step prompt or a stored prompt override. Turn-start and turn-complete events can move the task, while turn-complete and step-exit actions can disable plan mode. There is no regular standalone **stop agent** or **send prompt** workflow action. Approval/review steps and steps without automatic start remain the supported human gates. Inspect events on both the source and destination step before enabling a move or automatic start; otherwise two steps can form a loop.
|
||||
@@ -181,6 +190,9 @@ The HTTP equivalent is `POST /api/v1/tasks/:id/workspace-sources`, with `{ "sour
|
||||
|
||||
The task server runs inside agentctl's local runtime boundary. Its MCP routes do not use a separate bearer token. Do not expose agentctl ports; rely on the executor's process/network isolation and Kandev's session scoping.
|
||||
|
||||
<details>
|
||||
<summary>Office MCP and runtime CLI</summary>
|
||||
|
||||
## Office MCP and runtime CLI
|
||||
|
||||
Office runs use a smaller MCP surface than regular task-mode sessions. The built-in Office server registers exactly these tools:
|
||||
@@ -235,6 +247,11 @@ $KANDEV_CLI kandev task create \
|
||||
|
||||
Project list and create operations are forced to the workspace in the validated Office run token; the agent cannot select another workspace in these commands. Office runs cannot create or administer workspaces. Create additional workspaces through Kandev's user-facing setup and settings surfaces.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Profile and executor MCP</summary>
|
||||
|
||||
## Profile and executor MCP
|
||||
|
||||
An agent profile can add `stdio`, `http`, `sse`, or `streamable_http` servers when that agent supports MCP. The built-in Kandev task server is injected separately and cannot be replaced by a profile entry named `kandev`.
|
||||
@@ -247,6 +264,11 @@ Use the neutral plug button beside the chat composer to inspect the current sess
|
||||
|
||||
On desktop, hover or focus the button for the compact status list. On touch devices, tap its 44px target to open the same list in a bottom drawer. The report is per Kandev session and execution, so simultaneous agents in one task never share a status row. It stores only bounded, sanitized attachment facts: no MCP headers, environment values, tool arguments/results, raw ACP frames, or agent output.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>External MCP</summary>
|
||||
|
||||
## External MCP
|
||||
|
||||
Open **Settings > External MCP** (`/settings/external-mcp`) for client-specific snippets for Claude Code, Cursor, Codex, Auggie, OpenCode, and GitHub Copilot CLI.
|
||||
@@ -274,9 +296,16 @@ In external mode, `create_task_kandev` has no current task and does not accept t
|
||||
|
||||
External mode has no live Kandev session, so it does not expose `stop_task_kandev` or other task-scoped questions, plans, walkthroughs, sibling-session spawning, targeted session messages, branch operations, or step-completion signals. Some external tools can delete or materially reconfigure data; review the client's tool approvals.
|
||||
|
||||
</details>
|
||||
|
||||
### External MCP security boundary
|
||||
|
||||
The backend's `/mcp`, `/mcp/sse`, and `/mcp/message` routes currently have no Kandev authentication. They are reachable on every interface to which the backend is bound. Anyone who can reach them can attempt the exposed configuration and task mutations.
|
||||
The `/mcp`, `/mcp/sse`, and `/mcp/message` routes are mounted through
|
||||
`externalMCPAuthMiddleware`. With authentication disabled, they remain open for
|
||||
the current single-user behavior. When authentication is enabled, external
|
||||
clients must provide a personal access token; an already-authenticated browser
|
||||
session may also pass the same middleware. This is separate from task-mode MCP,
|
||||
which runs inside the agentctl session boundary.
|
||||
|
||||
- Bind the backend to loopback for a local single-user install.
|
||||
- For remote use, place the whole backend behind a VPN, firewall, or authenticated TLS reverse proxy.
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Change Kandev's Go backend across domain, API, event, persistence,
|
||||
|
||||
The Go module in `apps/backend/` builds both the unified `kandev` binary and the `agentctl` helper installed in task environments.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Find the owning domain before editing a handler or component.
|
||||
2. Run the smallest focused Go test with CGO and FTS5 enabled.
|
||||
3. Keep persistence, events, runtime lifecycle, and external calls behind their existing boundaries.
|
||||
4. Add fresh-schema, recovery, and failure-path tests for changed behavior.
|
||||
|
||||
## Run focused loops
|
||||
|
||||
Use `make dev` for normal full-stack work: it isolates state, starts Vite, and configures the backend proxy. A raw `make dev-backend` uses the normal application home unless you set an isolated `KANDEV_HOME_DIR`; see [Contributing](contributing.md).
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Install, start, and operate Kandev from the command line."
|
||||
|
||||
The `kandev` command starts a local Kandev backend, which serves the web UI, HTTP API, WebSocket API, and MCP endpoint. Use it when you want a browser-based installation or a headless/service process. For a packaged system WebView and desktop updates, use the [desktop app](./desktop-app.md) instead.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Install with Homebrew or npm.
|
||||
2. Run `kandev` and open the printed URL.
|
||||
3. Use `--headless` for a server or SSH session.
|
||||
4. Keep the backend on loopback unless a trusted proxy and authentication protect it.
|
||||
|
||||
## Supported release targets
|
||||
|
||||
| OS | Architectures | Install channels |
|
||||
@@ -96,6 +103,9 @@ kandev service <action> [service options]
|
||||
|
||||
These commands and options describe the installed native launcher. Unknown arguments fail with exit status 2. In particular, the npm and Homebrew release entrypoints currently invoke that native launcher, which does **not** support `dev`, `--dev`, `--runtime-version`, `--web-internal-port`, or the removed `--web-port` spelling. The source-checkout development launcher has a separate contract described below.
|
||||
|
||||
<details>
|
||||
<summary>Source checkout and service commands</summary>
|
||||
|
||||
### `dev` and the internal web port are source-checkout options
|
||||
|
||||
The repository's TypeScript launcher supports hot-reload development with this logical CLI syntax:
|
||||
@@ -145,6 +155,8 @@ kandev service logs --follow
|
||||
|
||||
Supported actions are `install`, `uninstall`, `start`, `stop`, `restart`, `status`, `logs`, and `config`. Installation accepts `--system`, `--run-as <user>` (only with `--system`), `--port`, `--home-dir`, and `--no-boot-start`. Reinstalling an existing Kandev-managed system service preserves its account unless `--run-as` is supplied explicitly. A first system install from a root login requires `--run-as`, including `--run-as root` when root is intentional. In the current native installer, `--port` is written as `KANDEV_SERVER_PORT`, but the supervising launcher overwrites that value with its own automatic port selection; the option therefore does not reliably pin a service listener today. The service normally prefers `38429` and falls back when it is busy. Windows service installation is not implemented. Managed user services write owner-only install metadata so **Settings > System > Updates** can offer the guarded Apply action; system services and failed guarded updates use the package manager followed by `kandev service install` and `kandev service restart`. See [Run as a service](./run-as-a-service.md) for privileges, paths, upgrades, and recovery.
|
||||
|
||||
</details>
|
||||
|
||||
## Ports and network exposure
|
||||
|
||||
| Process | Preferred port | Automatic behavior |
|
||||
|
||||
@@ -13,6 +13,13 @@ Kandev has three distinct configuration surfaces:
|
||||
|
||||
This page is the startup-configuration reference. Executor-specific fields are covered in [Executors](./executors.md), and deployment examples are in [Docker](./docker.md), [Kubernetes](./k8s.md), and [Run as a service](./run-as-a-service.md).
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Use the built-in profile defaults for a first run.
|
||||
2. Add `config.yaml` only for stable operator-wide settings.
|
||||
3. Use environment variables for deployment-specific overrides and secrets.
|
||||
4. Use the web UI for persistent product settings, agents, executors, and workflows.
|
||||
|
||||
## Load order and lifecycle
|
||||
|
||||
At backend startup, later sources override earlier ones:
|
||||
@@ -41,6 +48,9 @@ Some common camelCase keys have explicit compatibility aliases. Use the document
|
||||
|
||||
### Root and server
|
||||
|
||||
<details>
|
||||
<summary>Complete backend startup reference</summary>
|
||||
|
||||
| YAML key | Environment variable | Default | Current behavior |
|
||||
|---|---|---|---|
|
||||
| `homeDir` | `KANDEV_HOME_DIR` | `~/.kandev` | Root for data, tasks, worktrees, cloned repositories, sessions, and logs. A leading `~/` expands. |
|
||||
@@ -288,6 +298,8 @@ features:
|
||||
|
||||
Copying this entire file is unnecessary and can freeze old defaults in a deployment. Keep only deliberate overrides. On Windows, do not copy the Unix Docker host/path literals from this example.
|
||||
|
||||
</details>
|
||||
|
||||
## Runtime feature toggles
|
||||
|
||||
**Settings → System → Feature Toggles** manages startup-time flags:
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Set up Kandev, find the owning subsystem, run focused checks, upda
|
||||
|
||||
Kandev combines a Go server and native launcher, a Vite/React web client, a TypeScript development supervisor and npm shim, a Tauri desktop shell, and task-environment helpers. Begin at the subsystem that owns the behavior; do not recreate its rules in a neighboring layer.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Run `make bootstrap` once in a fresh checkout.
|
||||
2. Use `make dev` for normal full-stack work.
|
||||
3. Find the owning backend, web, CLI, desktop, or runtime boundary before editing.
|
||||
4. Run focused checks, update public docs, and leave a small reviewable diff.
|
||||
|
||||
## Set up the repository
|
||||
|
||||
The pinned toolchain in `mise.toml` currently includes Node 24, pnpm 9.15.9, Go 1.26.0, and supporting tools.
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Coordinate parallel sessions, subtasks, repositories, branches, me
|
||||
|
||||
Kandev can coordinate several agents without turning every unit of work into a separate task. Choose the smallest boundary that gives the work the isolation, workflow state, and review surface it needs.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Use another session for parallel work in the same task environment.
|
||||
2. Use a subtask when work needs its own workflow state.
|
||||
3. Choose an isolated workspace for concurrent writers or a different repository.
|
||||
4. Send bounded messages and keep the human review gate explicit.
|
||||
|
||||
## Choose a coordination boundary
|
||||
|
||||
| Need | Use | Filesystem relationship | Independent workflow state |
|
||||
@@ -154,6 +161,9 @@ It ignores archived and ephemeral children, ignores grandchildren, and does not
|
||||
|
||||
For a human gate, use **On Turn Complete → Do nothing (wait for user)** and require a person to review before moving the task or sending the next instruction. `step_complete_kandev` proves only that the agent emitted the configured completion signal.
|
||||
|
||||
<details>
|
||||
<summary>Work across repositories and branches</summary>
|
||||
|
||||
## Work across repositories and branches
|
||||
|
||||
### Create a multi-repository task
|
||||
@@ -168,8 +178,13 @@ Before starting, document:
|
||||
- the merge order for dependent changes; and
|
||||
- the test command required in each repository.
|
||||
|
||||
</details>
|
||||
|
||||
### Add sources after creation
|
||||
|
||||
<details>
|
||||
<summary>Adding sources details</summary>
|
||||
|
||||
For an idle, non-archived repository-backed task, use **Files → Workspace actions → Add Repositories to workspace**. **Add repository** offers a workspace repository, an existing local Git checkout, or a provider-backed/pasted remote URL. The workspace option shares task creation's saved/discovered selector, including refresh and create-repository actions. **Add folder** appears when the executor supports it. Add multiple mixed sources together; validation, persistence, and materialization are atomic. Desktop uses a dialog and phones use a full-height drawer with a touch-sized repository menu.
|
||||
|
||||
Repository sources work on **Worktree**, **Local/Local PC**, **Local Docker**, **SSH**, and **Sprites**. Folder sources are live host grants and work only on **Worktree** and **Local/Local PC**; they are unavailable to Docker and remote runtimes. Remote Docker remains unimplemented. Local Git sources need a cloneable origin on Docker, SSH, and Sprites; Worktree and Local/Local PC can use host repositories directly.
|
||||
@@ -201,6 +216,8 @@ Use `update_repository_base_branch_kandev` with a task-repository ID to change t
|
||||
|
||||
Separate worktrees isolate file state. They do not by themselves isolate host credentials, ports, background processes, or other machine resources.
|
||||
|
||||
</details>
|
||||
|
||||
## Keep durable coordination state
|
||||
|
||||
Regular tasks have one versioned plan. Use the parent plan for the overall breakdown, then put each child's precise scope and file ownership in that child's description. A subtask does not share a second live copy of the parent plan.
|
||||
@@ -216,6 +233,9 @@ Before handing work to another session or task, record:
|
||||
|
||||
Commit before switching isolated branches when the repository process requires it. Conversation summaries are useful context, but plans, repository files, commits, and pull requests are the durable sources of truth.
|
||||
|
||||
<details>
|
||||
<summary>Coordinator-led and human-led patterns</summary>
|
||||
|
||||
## Coordinator-led and human-led patterns
|
||||
|
||||
A supported coordinator-led Kanban flow is:
|
||||
@@ -241,6 +261,8 @@ Regular Kanban does not currently expose a dependency editor or blocker filter.
|
||||
|
||||
When Office is enabled, it prototypes **Blocked by** and **Blocking** properties with same-workspace, self-reference, and cycle validation. Treat these as an evaluation surface rather than a production coordination contract.
|
||||
|
||||
</details>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **New Agent has no usable profile:** configure credentials under **Settings → Agents** and a compatible executor under **Settings → Executors**.
|
||||
|
||||
@@ -9,6 +9,13 @@ Kandev Desktop packages the native Kandev runtime inside a Tauri application and
|
||||
|
||||
The [CLI](./cli.md) is a better fit for headless machines, browser-only access, or an OS service. Desktop and CLI releases use the same SemVer and the same default Kandev data layout, but they are separate installation and update channels.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Download the installer for your platform from GitHub Releases.
|
||||
2. Verify its checksum.
|
||||
3. Install and launch Kandev.
|
||||
4. Use the in-app updater only when a signed update feed is available; otherwise install the next verified artifact manually.
|
||||
|
||||
## Supported artifacts
|
||||
|
||||
Download artifacts from [GitHub Releases](https://github.com/kdlbs/kandev/releases). Each desktop filename begins with `kandev-desktop-<platform>-`; use the installer format for your platform, not an updater archive.
|
||||
|
||||
@@ -7,6 +7,12 @@ description: "Use quick chat, utility agents, saved prompts, voice input, editor
|
||||
|
||||
Kandev includes short-lived chat, reusable AI helpers, dictation, file and editor integration, language servers, and terminals. Some tools run in a task environment; others run on the Kandev backend host or in the browser. That boundary determines which files, executables, credentials, and network services they can reach.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Use **Quick Chat** for disposable questions.
|
||||
2. Use a task session for work that needs files, review, or workflow state.
|
||||
3. Add utility agents, editors, language servers, or terminals only when their host boundary is acceptable.
|
||||
|
||||
## Quick Chat
|
||||
|
||||
Quick Chat is an agent conversation outside the board. Use it for repository orientation, experiments, and disposable questions that do not need workflow state, review gates, dependencies, or a delivery record.
|
||||
@@ -45,6 +51,9 @@ Closing a real chat tab permanently deletes its conversation, hidden backing tas
|
||||
|
||||
If **Start chat** is disabled, select a profile and finish every repository/branch row. If a repository is missing, confirm that it belongs to the current workspace and refresh the repository configuration. Use a normal task when the result must remain visible on a board or become a reviewed PR.
|
||||
|
||||
<details>
|
||||
<summary>Utility agents and configuration chat</summary>
|
||||
|
||||
## Utility agents
|
||||
|
||||
Open **Settings > Utility Agents** (`/settings/utility-agents`). Utility agents are one-shot ACP calls used to generate small pieces of text; they do not create a durable task conversation.
|
||||
@@ -75,8 +84,13 @@ Configuration Chat uses a repository-less ephemeral task. Its configuration-mode
|
||||
|
||||
Closing the floating Settings panel preserves the conversation. To delete it, open it in Quick Chat, close its tab, and confirm deletion. Configuration tasks are excluded from the seven-day Quick Chat sweeper and remain available until explicitly deleted or their workspace is deleted.
|
||||
|
||||
</details>
|
||||
|
||||
## Saved prompts
|
||||
|
||||
<details>
|
||||
<summary>Saved prompt details</summary>
|
||||
|
||||
Open **Settings > Prompts** (`/settings/prompts`) to add, edit, or delete reusable prompts. A saved prompt needs a unique name and non-empty content.
|
||||
|
||||
Type `@` in the task chat composer and select a prompt. The visible message keeps the `@name`; Kandev expands the prompt content into hidden system context for the agent. References are recognized only at the start of the text or after whitespace and must match the stored name. Prompt content can reference other saved prompts. Expansion stops at a depth of eight, skips cycles, and includes each prompt only once.
|
||||
@@ -95,8 +109,13 @@ Built-ins are marked in the UI but remain editable. Editing `ci-auto-fix` or `ch
|
||||
|
||||
A saved prompt is an instruction, not an authorization or policy boundary. Executor permissions, human gates, tests, and provider protections still control what can happen.
|
||||
|
||||
</details>
|
||||
|
||||
## Voice Mode
|
||||
|
||||
<details>
|
||||
<summary>Voice details</summary>
|
||||
|
||||
Open **Settings > Voice Mode** (`/settings/voice-mode`). Voice Mode inserts a transcript at the cursor in the active chat composer.
|
||||
|
||||
Defaults are:
|
||||
@@ -128,8 +147,15 @@ Engine choice is capability selection, not runtime failover. Once recognition or
|
||||
|
||||
Microphone capture requires browser permission and normally HTTPS or localhost. Whisper Web also needs `getUserMedia`, `MediaRecorder`, workers, enough browser storage, and a first-use network download. The UI mentions common Chrome, Edge, and Safari versions, but Kandev does not enforce a browser/version allow-list; runtime availability is determined from the required APIs. If recording fails, check site permission, input device, secure context, model download/cache, browser support, and network access. The composer must remain enabled; switching tasks or disabling the input cancels recording.
|
||||
|
||||
</details>
|
||||
|
||||
## Files and editor integrations
|
||||
|
||||
> **Security:** Embedded VS Code runs code-server with `--auth none` inside the task environment. Use it only with a trusted executor and network boundary.
|
||||
|
||||
<details>
|
||||
<summary>Editor, language-server, and terminal details</summary>
|
||||
|
||||
For an idle, non-archived repository-backed task, **Files → Workspace actions → Add Repositories to workspace** opens a tab-free source picker. **Add repository** offers a workspace repository, a local Git checkout, or a provider-backed/pasted remote URL. The workspace option shares task creation's saved/discovered selector, refresh, and create-repository actions. **Add folder** is available on Local/Local PC or Worktree. Every repository chooses one base branch, and Local/Local PC uses the current checkout without switching it. Desktop uses a dialog; phones use a full-height drawer with a touch-sized repository menu. A mixed submission is atomic, and repository additions refresh repository-aware tools while folders remain Files-only. See [Tasks and workflows](tasks-and-workflows.md#add-sources-to-an-existing-task).
|
||||
|
||||
The task **Files** panel browses, searches, opens, and edits task-worktree files. Kandev rejects file paths that escape the resolved worktree. A session with one worktree opens that worktree directly in a host editor. When a session has several worktrees, the editor button asks which repository or worktree to open, and each configured editor in the adjacent menu expands to the same repository-and-branch picker. Check that selection before launching an editor from a multi-repository task. Older API clients that omit `worktree_id` retain the first-worktree fallback.
|
||||
@@ -203,6 +229,8 @@ Shell changes apply whenever a new or restarted terminal is created, including i
|
||||
|
||||
If no terminal can be created, wait for the task environment to become ready and confirm its executor is reachable. If a reopened terminal is dead, create a new one; the original PTY or remote connection may have exited.
|
||||
|
||||
</details>
|
||||
|
||||
## Choose the right surface
|
||||
|
||||
| Need | Use |
|
||||
|
||||
+12
-2
@@ -33,6 +33,9 @@ Kandev currently has no built-in multi-user web login or API authorization bound
|
||||
|
||||
## Published images
|
||||
|
||||
<details>
|
||||
<summary>Published image details</summary>
|
||||
|
||||
The release workflow publishes multi-architecture `linux/amd64` and `linux/arm64` images to `ghcr.io/kdlbs/kandev`.
|
||||
|
||||
| Flavor | Moving tag | Version tags | Contents |
|
||||
@@ -65,6 +68,13 @@ RUN apt-get update \
|
||||
|
||||
Leaving the final configured user as root is intentional for this base flavor: the inherited entrypoint repairs `/data` and drops to `kandev` before starting the command. If a derivative finishes with `USER kandev`, provision writable volume ownership in advance, as the universal flavor does.
|
||||
|
||||
</details>
|
||||
|
||||
> **Persistence:** Always mount `/data`. Removing a container without a volume removes its database, workspaces, installed agent CLIs, and authentication state.
|
||||
|
||||
<details>
|
||||
<summary>Image runtime behavior and persistence details</summary>
|
||||
|
||||
## Image runtime behavior
|
||||
|
||||
The base image:
|
||||
@@ -79,8 +89,6 @@ The universal derivative sets `USER kandev`, so it skips the base entrypoint's r
|
||||
|
||||
## Persistence
|
||||
|
||||
Always mount `/data`. Removing a container without a volume removes its database, workspaces, installed agent CLIs, and authentication state.
|
||||
|
||||
| Volume path | Data |
|
||||
|---|---|
|
||||
| `/data/data/` | SQLite `kandev.db`, WAL/SHM files, and SQLite backup snapshots |
|
||||
@@ -113,6 +121,8 @@ docker exec --user kandev -it kandev sh
|
||||
|
||||
The same rule applies to `claude login`, `codex login`, and manual `npm install -g` commands. Treat `/data/home` and the database as secret material when backing them up.
|
||||
|
||||
</details>
|
||||
|
||||
## Configuration
|
||||
|
||||
Pass backend settings as environment variables or mount a read-only `/etc/kandev/config.yaml`. See [Configuration](configuration.md) for the canonical field names, environment mapping, validation, and precedence.
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Choose and configure local, worktree, Docker, SSH, or Sprites task
|
||||
|
||||
An executor determines where Kandev creates a task environment and runs `agentctl`, the selected agent, terminals, and Git commands. An executor profile supplies reusable settings for that executor. A task environment is the concrete workspace created for one task; several sessions may reuse it.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Choose **Worktree** for normal isolated Git work.
|
||||
2. Choose **Local** only when sharing the selected checkout is intentional.
|
||||
3. Choose Docker, SSH, or Sprites when the host boundary or remote location is part of the requirement.
|
||||
4. Review credentials, scripts, mounts, and network policy as part of the executor trust boundary.
|
||||
|
||||
## Current support
|
||||
|
||||
| Executor | Current status | Workspace | Use it when |
|
||||
@@ -150,6 +157,11 @@ Source batches are atomic: if validation, cloning, or runtime adoption fails, Ka
|
||||
|
||||
## Local Docker
|
||||
|
||||
> **Daemon authority:** Dockerfile instructions run with the configured daemon's authority. Treat profile creation as an administrative operation on that daemon.
|
||||
|
||||
<details>
|
||||
<summary>Local Docker details</summary>
|
||||
|
||||
### Prerequisites and profile creation
|
||||
|
||||
Install a reachable Docker Engine and leave `docker.enabled: true` (the non-containerized backend default). The published Kandev service image overrides this to `false`; see [Docker](docker.md#using-docker-for-agent-environments). The runtime health method is currently a no-op and the client is initialized lazily, so a green control-plane startup does not prove daemon access; image build or first task launch is the effective check.
|
||||
@@ -180,8 +192,15 @@ The current container manager always selects the Linux/amd64 `agentctl` helper.
|
||||
|
||||
Kandev passes each agent definition's CPU and memory limits to Docker. These are agent implementation defaults, not executor-profile controls. Apply additional daemon, cgroup, storage, and network policy outside Kandev when required.
|
||||
|
||||
</details>
|
||||
|
||||
### Credentials and security
|
||||
|
||||
> **Trust boundary:** A container is useful but not a hostile-code sandbox. The daemon has host-level power, bind mounts expose sources, agents can use injected secrets, and the default image has outbound network access. Kandev does not mount the Docker socket automatically.
|
||||
|
||||
<details>
|
||||
<summary>Docker credential and security details</summary>
|
||||
|
||||
Docker profiles can inject resolved environment secrets. For agent file-based authentication, Kandev selectively seeds a per-execution directory under `<KANDEV_HOME_DIR>/agent-sessions/` and mounts that directory at the agent's expected config path. It does not intentionally mount the entire host home.
|
||||
|
||||
A container is a useful boundary, not a hostile-code security sandbox. The Docker daemon has host-level power, bind mounts expose their sources, the agent can use every injected secret, and the default image has outbound network access. Kandev does **not** mount the Docker socket into agent containers automatically.
|
||||
@@ -192,8 +211,15 @@ Plain Stop preserves a healthy container for resume. A later launch reconnects t
|
||||
docker ps -a --filter label=kandev.managed=true
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Sprites.dev
|
||||
|
||||
> **Credentials and network:** Sprites sandboxes receive highly sensitive data. Credential upload is best effort, and network policy is installed only after credential upload, prepare, controller startup, and agent-instance creation; bootstrap traffic may happen first, so the policy is not a security boundary.
|
||||
|
||||
<details>
|
||||
<summary>Sprites.dev details</summary>
|
||||
|
||||
### Configure
|
||||
|
||||
1. Save the provider token as a Kandev secret.
|
||||
@@ -209,8 +235,15 @@ Fresh launch creates a sandbox named `kandev-<execution-prefix>`, uploads the Li
|
||||
|
||||
Plain Stop preserves the sandbox and workspace for resume. Archive/delete terminal stops attempt to destroy it, and the profile page can list and explicitly destroy Kandev-named sandboxes with the selected provider token. **Reset Environment** also requests sandbox destruction, but the current direct-reset path does not carry the profile's Sprites secret into that destroy request; after a reset or backend restart, verify the old sandbox in the profile page and destroy it there if it remains. Provider retention, quotas, network behavior, and billing remain provider-dependent. Destroying a sandbox out of band breaks any session that still references it.
|
||||
|
||||
</details>
|
||||
|
||||
## SSH
|
||||
|
||||
> **Trust boundary:** Verify the target host fingerprint before saving. Kandev pins the target key, but unknown ProxyJump bastion keys may be accepted on first use; remote credential transfers write sensitive material under the remote user's home.
|
||||
|
||||
<details>
|
||||
<summary>SSH details</summary>
|
||||
|
||||
SSH is implemented as a separate remote connection per session. Kandev uploads a platform-matched `agentctl` helper over SFTP, starts it in the remote task directory, and forwards its port to local loopback.
|
||||
|
||||
### Host requirements
|
||||
@@ -241,14 +274,23 @@ The profile editor exposes remote shell and agent-readiness checks. Backend/API
|
||||
|
||||
The remote-auth card is built from the currently enabled agents. Depending on an agent's declared methods, it can copy selected local credential files, resolve a stored secret into that agent's authentication environment variable, or run an agent-specific setup script on the remote host. GitHub can use an explicitly selected `GITHUB_TOKEN` secret as an unmanaged profile override; Kandev does not copy the host-active `gh` token. These transfers write sensitive material under the remote user's home and are best-effort—verify authentication on the remote after saving. Although the profile editor also stores Git name/email controls for SSH, the current SSH runtime does not apply them; configure Git identity on the remote host yourself.
|
||||
|
||||
</details>
|
||||
|
||||
### Repository sources and cleanup
|
||||
|
||||
> **Cleanup:** SSH task directories, session-runtime data, and cached helpers may remain after disconnect. Audit remote processes and paths before deleting anything.
|
||||
|
||||
<details>
|
||||
<summary>SSH repository source details</summary>
|
||||
|
||||
SSH materializes attached repository sources in the remote task directory. It still ignores profile prepare and cleanup scripts. Ensure the remote host has the required Git credentials and can reach every selected remote; folders cannot be attached to SSH tasks.
|
||||
|
||||
The runtime preflights the selected agent command and reports an installation hint when missing; it does not install the agent or its toolchain. Only these resolved credential environment names are forwarded to the remote agent: `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GITHUB_TOKEN`, and `GH_TOKEN`. Arbitrary profile variables and control-plane process variables are not forwarded to that agent process. Agent-specific auth setup scripts can still consume a selected stored secret and materialize their own remote login state.
|
||||
|
||||
Stop attempts to kill the session's remote `agentctl` and remove only the remote session-runtime directory, then closes forwarding and SSH. Remote cleanup is best-effort: when the connection has already failed, the process or session directory can remain. The task directory always remains and no background sweeper currently removes it. The cached helper and checksum at `~/.kandev/bin/agentctl` and `agentctl.sha256` also remain for later sessions. Periodically audit the remote process list, session directories, and `<workdir-root>/tasks/` after confirming no session needs the data. Resume re-dials SSH and reuses a live recorded PID when possible; otherwise Kandev starts a fresh remote controller.
|
||||
|
||||
</details>
|
||||
|
||||
## Lifecycle and cleanup
|
||||
|
||||
The task environment reports `creating`, `ready`, `stopped`, or `failed`; individual execution records have finer states. Stop is deliberately not synonymous with destroy for resumable Docker and Sprites environments.
|
||||
|
||||
@@ -7,6 +7,17 @@ description: "Add agents, executors, integrations, workflow behavior, MCP tools,
|
||||
|
||||
An extension is complete when discovery/configuration, durable state, runtime behavior, recovery, security, tests, packaging, and public documentation agree. Registration and UI presence alone are not completion.
|
||||
|
||||
## Choose an extension seam
|
||||
|
||||
- **Agent:** add a CLI runtime or structured ACP integration.
|
||||
- **Executor:** add a task environment and lifecycle backend.
|
||||
- **Provider:** add an external service connection, health, and UI.
|
||||
- **Workflow/MCP:** add durable automation behavior or a scoped tool.
|
||||
- **Plugin:** ship an independently versioned extension.
|
||||
- **Settings/workbench:** add a user-facing surface after backend ownership exists.
|
||||
|
||||
Use the smallest seam that owns the behavior, then follow the completion checklist at the end.
|
||||
|
||||
## Add an agent
|
||||
|
||||
For a local passthrough-only CLI, users can choose **Settings → Agents → Add TUI Agent**. That path persists a custom definition and default profile; no source patch is required.
|
||||
|
||||
@@ -9,6 +9,13 @@ This inventory describes the current `main` branch. A capability counts as shipp
|
||||
|
||||
Released builds can lag this page. Check **Settings > System > About** or `kandev --version` and compare the matching GitHub tag when behavior differs.
|
||||
|
||||
## How to use this page
|
||||
|
||||
- Start with **Supported** for the normal product path.
|
||||
- Read **Dependency-bound** and **Limited** before choosing a provider, executor, or platform.
|
||||
- Treat **Experimental**, **In progress**, and **Internal** as non-contract surfaces.
|
||||
- Verify the running version and a small representative workflow before trusting a boundary.
|
||||
|
||||
## Status meanings
|
||||
|
||||
| Status | Meaning |
|
||||
@@ -20,6 +27,9 @@ Released builds can lag this page. Check **Settings > System > About** or `kande
|
||||
| In progress | Source, schema, tests, a flag, or a stub exists, but there is no supported production workflow yet. |
|
||||
| Internal | Development, test, diagnostic, or implementation support rather than an end-user feature. |
|
||||
|
||||
<details>
|
||||
<summary>Tasks, workflows, and coordination</summary>
|
||||
|
||||
## Tasks, workflows, and coordination
|
||||
|
||||
| Capability | Status | Current boundary |
|
||||
@@ -41,6 +51,11 @@ Released builds can lag this page. Check **Settings > System > About** or `kande
|
||||
| GitHub-backed workflow sync | Dependency-bound | Requires GitHub access. Synced workflows are read-only in Kandev and guarded updates can need local agent/executor mapping. |
|
||||
| Coordinator-led teams, participants/quorum, arbitrary task trees, routines, budgets, and heartbeats | In progress | These belong to Office. Office is disabled in the production profile and remains an evolving, feature-flagged autonomy layer. |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Sessions, review, and developer tools</summary>
|
||||
|
||||
## Sessions, review, and developer tools
|
||||
|
||||
| Capability | Status | Current boundary |
|
||||
@@ -60,6 +75,11 @@ Released builds can lag this page. Check **Settings > System > About** or `kande
|
||||
| Integrated shell terminals | Dependency-bound | Create, reopen, rename, and terminate are shipped. Shell settings affect new terminals, and executor/task-environment availability controls where the PTY runs. |
|
||||
| Prompts, keyboard shortcuts, notifications, appearance, and task actions | Supported | These are normal settings surfaces. Browser notification permission, custom command validity, and local shell/editor availability still apply to their effects. |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Agents, executors, integrations, and automation</summary>
|
||||
|
||||
## Agents, executors, integrations, and automation
|
||||
|
||||
| Capability | Status | Current boundary |
|
||||
@@ -84,6 +104,11 @@ Released builds can lag this page. Check **Settings > System > About** or `kande
|
||||
| GitHub push and CI automation triggers | In progress | Trigger types and UI labels exist as coming-soon/stub paths; they are not working production triggers. GitHub's separate opt-in PR CI-fix automation is shipped. |
|
||||
| Automation Run mode | Limited | Creates a hidden ephemeral task and starts immediately. It cannot require user input. Automatic worktree/branch reaping applies only when a Worktree runtime ID is present; other executors follow their own lifecycle. |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>MCP, clients, and operation</summary>
|
||||
|
||||
## MCP, clients, and operation
|
||||
|
||||
| Capability | Status | Current boundary |
|
||||
@@ -104,6 +129,8 @@ Released builds can lag this page. Check **Settings > System > About** or `kande
|
||||
| Plugin system | Supported | The plugin system ships in the base product with no feature flag: install/manage plugins, spawn plugin backends, and load native UI bundles. Loaded plugin code runs with backend privileges, so install only plugins you trust; manifest schema, capabilities, and host API may still change between releases. |
|
||||
| Mock providers and E2E-only routes | Internal | They are selected only by development/test runtime profiles and must not be exposed as product integrations. |
|
||||
|
||||
</details>
|
||||
|
||||
## Publication boundary
|
||||
|
||||
Published user documentation lives in `docs/public/**`. Files elsewhere under `docs/**` can be proposed ADRs, draft specifications, implementation plans, test notes, or historical decisions. Their presence does not change a row above.
|
||||
|
||||
@@ -9,6 +9,13 @@ Kandev runs Git commands in the selected repository workspace for a task session
|
||||
|
||||
Use the task's **Changes** panel to inspect, stage, discard, commit, push, reset, or rename a branch. The task toolbar and command panel also expose **Commit Changes**, **Push**, **Pull**, provider-appropriate pull-request or merge-request creation, **Rebase**, and **Merge** when a Git-capable session is selected.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Inspect the selected repository in **Changes**.
|
||||
2. Stage only the files you intend to commit.
|
||||
3. Run required checks before pushing or opening a change request.
|
||||
4. Treat discard, reset, amend, force-push, and cleanup as irreversible or history-changing operations.
|
||||
|
||||
## Prerequisites and trust boundary
|
||||
|
||||
The repository must be a valid Git checkout in the executor workspace and the session's `agentctl` must be reachable. Remote commands use the remote named `origin`; configure its URL and credentials before relying on Pull, Push, Rebase, Merge, or change-request creation.
|
||||
@@ -111,6 +118,9 @@ Title is required. Body and base branch may be empty. GitHub and Azure delegate
|
||||
|
||||
For GitLab, Kandev preserves a self-managed connection's scheme and never retries against another host. It prefers `glab` when installed and uses the workspace-injected `GITLAB_TOKEN` REST path when the CLI is absent or its create command fails. The successful WebSocket payload keeps the compatibility field name `pr_url` and adds `provider:"gitlab"`. Association runs after that response; use **Link GitLab merge request** if the MR was created but the link is missing.
|
||||
|
||||
<details>
|
||||
<summary>WebSocket operation reference</summary>
|
||||
|
||||
## WebSocket operation reference
|
||||
|
||||
These are the registered Kandev WebSocket actions. Every payload requires `session_id`; `repo` is optional only for a single-repository workspace.
|
||||
@@ -164,6 +174,8 @@ Read-only Git actions used by the Changes panel include `session.commit_diff`, `
|
||||
|
||||
`agentctl` also implements `/api/v1/git/*` HTTP routes inside the execution runtime. Those routes are an internal backend-to-runtime control surface, not the public Kandev backend API. External clients should not discover or expose executor-local agentctl ports; use the registered Kandev WebSocket actions.
|
||||
|
||||
</details>
|
||||
|
||||
## Cleanup and data loss
|
||||
|
||||
Worktree cleanup runs the repository cleanup script, forcibly removes the Git worktree directory, and may remove the local branch:
|
||||
|
||||
+26
-4
@@ -5,11 +5,21 @@ description: "Choose a guide for installing Kandev, running agent work, reviewin
|
||||
|
||||
# Kandev Documentation
|
||||
|
||||
Kandev is an open-source workbench for assigning repository work to coding agents, coordinating parallel sessions, and reviewing the resulting changes. It runs on infrastructure you control. Agent CLIs, models, executors, and external services remain separate dependencies with their own credentials and limits.
|
||||
Kandev lets you assign repository work to coding agents, review the result, and keep control of the environment and credentials.
|
||||
|
||||
## Run work in Kandev
|
||||
## Start here
|
||||
|
||||
Start with the page that matches the job in front of you:
|
||||
1. [Get started](use-kandev.md) — install Kandev, add a repository, and run a first task.
|
||||
2. [Tasks and workflows](tasks-and-workflows.md) — create work, choose a workflow, and use plans.
|
||||
3. [Sessions and review](sessions-and-review.md) — supervise an agent, inspect changes, and finish safely.
|
||||
4. [Security and trust](security.md) — choose an appropriate access boundary before sharing Kandev with others.
|
||||
|
||||
<details>
|
||||
<summary>More guides for running work</summary>
|
||||
|
||||
### Run work in Kandev
|
||||
|
||||
Choose the guide that matches the job in front of you:
|
||||
|
||||
- [Get started](use-kandev.md): install Kandev, add a local repository, configure an agent, and run a first task.
|
||||
- [Tasks and workflows](tasks-and-workflows.md): create tasks, use plans, configure workflow steps, and understand the Office-only document and label boundary.
|
||||
@@ -24,7 +34,12 @@ Start with the page that matches the job in front of you:
|
||||
- [Feature status](feature-status.md): check support boundaries, dependencies, experimental features, and unfinished work.
|
||||
- [Security and trust](security.md): choose a safe deployment boundary, constrain agent access, protect credentials, and preserve human review.
|
||||
|
||||
Installation and operation have dedicated references: [CLI](cli.md), [desktop app](desktop-app.md), [configuration](configuration.md), [service](run-as-a-service.md), [Docker](docker.md), [Kubernetes](k8s.md), and [operations](operations.md).
|
||||
Installation and operation: [CLI](cli.md), [desktop app](desktop-app.md), [configuration](configuration.md), [service](run-as-a-service.md), [Docker](docker.md), [Kubernetes](k8s.md), and [operations](operations.md).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Contributor guides</summary>
|
||||
|
||||
## Contribute to Kandev
|
||||
|
||||
@@ -41,12 +56,19 @@ These pages describe the current source tree and its development conventions:
|
||||
- [Release process](release-process.md): understand versioning and the CLI, runtime, desktop, npm, Homebrew, and container release paths.
|
||||
- [Public docs guide](README.md): update or add a published page.
|
||||
|
||||
</details>
|
||||
|
||||
## Supported product boundary
|
||||
|
||||
The regular Kanban workbench, task sessions, review surfaces, and task-scoped Kandev MCP are the supported product path. Some capabilities still depend on a particular agent, executor, provider, platform, credential, or install channel; those differences are called out on their topic pages.
|
||||
|
||||
**Office is separate, disabled in the production runtime profile, feature-flagged, and still in progress.** Its source, tests, specifications, and internal plans do not make persistent teams, routines, budgets, or coordinator-led autonomy a supported production contract. See [Feature status](feature-status.md) for that boundary and [Office provider routing](office-provider-routing.md) for the feature-flagged routing surface.
|
||||
|
||||
<details>
|
||||
<summary>Version matching</summary>
|
||||
|
||||
## Match docs to the running version
|
||||
|
||||
These docs describe the current `main` branch and are not versioned. A released build can lag behind them. Check **Settings > System > About** or run `kandev --version`, then use the matching GitHub tag when exact historical behavior matters.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Connect Azure DevOps, GitHub, GitLab, Jira, Linear, Sentry, and Sl
|
||||
|
||||
Integrations let Kandev's backend read and update provider data. They power repository and issue browsers, task associations, watches, pull-request review, and provider-specific task launchers.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Open the integration for the workspace that owns the work.
|
||||
2. Connect the narrowest provider credential that supports the task.
|
||||
3. Test the connection before browsing or enabling watches.
|
||||
4. Keep provider API credentials, task Git credentials, and agent credentials separate.
|
||||
|
||||
They do **not** provide every credential a task needs. Keep these paths distinct:
|
||||
|
||||
- an integration credential lets the Kandev backend call a provider API;
|
||||
@@ -45,6 +52,9 @@ Health results are cached and periodically refreshed (normally about every 90 se
|
||||
|
||||
## GitHub
|
||||
|
||||
<details>
|
||||
<summary>GitHub details</summary>
|
||||
|
||||
Use GitHub for pull requests, issues, reviews, checks, repository discovery, task associations, and provider-triggered work. Browse it at `/github` after connecting an account.
|
||||
|
||||
### Authenticate
|
||||
@@ -257,8 +267,13 @@ For recovery:
|
||||
registration, rotate the credentials in GitHub, and add the App again. Kandev does not rotate App
|
||||
private keys, OAuth client secrets, or webhook secrets automatically.
|
||||
|
||||
</details>
|
||||
|
||||
### Configure and use the workspace
|
||||
|
||||
<details>
|
||||
<summary>Workspace GitHub details</summary>
|
||||
|
||||
Workspace GitHub settings control repository scope, default/saved searches, quick-action prompts, pull-request analytics, review watches, and issue watches. At `/github`, search or browse pull requests and issues, save queries, apply prompt presets, and launch a Kandev task. A saved query can default to one repository; choose **All repos** for no repository default, and change the repository filter without rewriting the saved query. An associated pull request also appears in task review surfaces for feedback, checks, reviews, and merge actions.
|
||||
|
||||
A **Review Watch** polls a GitHub search and creates review work. It requires a workflow, starting step, prompt, and workspace. The default query is `type:pr state:open review-requested:@me -is:draft`; add repository filters or replace the query as needed. An optional agent or executor profile overrides the selected step's defaults. The poll interval defaults to 300 seconds and accepts 60–3,600 seconds. The prompt field accepts `@name` references to saved prompts, resolved the same way as in a workflow step; see [Saved prompt references in step prompts](workflow-tips.md#saved-prompt-references-in-step-prompts).
|
||||
@@ -288,8 +303,13 @@ observed event without prescribing an action; the task workflow and agent
|
||||
context determine the response. Destination workflow steps and GitLab lifecycle
|
||||
parity are follow-up work.
|
||||
|
||||
</details>
|
||||
|
||||
## GitLab
|
||||
|
||||
<details>
|
||||
<summary>GitLab details</summary>
|
||||
|
||||
GitLab supports workspace-scoped connections, issue and merge-request browsing, task launch and durable MR links, automation watches, linked-MR review actions, and merge-request creation. GitHub and GitLab can be connected at the same time; each provider uses its own credentials and records.
|
||||
|
||||
### Connect a workspace
|
||||
@@ -342,8 +362,13 @@ For a task repository whose `origin` matches the workspace's GitLab host, the Ch
|
||||
|
||||
A successful create returns the MR URL and asynchronously records it against the originating task repository. If association fails, use the manual link action. Retrying is idempotent for an existing open MR with the same source and target branches. A push can succeed even when MR creation fails; Kandev reports that partial result and leaves the remote branch in place for retry.
|
||||
|
||||
</details>
|
||||
|
||||
## Azure DevOps
|
||||
|
||||
<details>
|
||||
<summary>Azure DevOps details</summary>
|
||||
|
||||
Azure DevOps configuration is workspace-specific. The current integration supports Azure DevOps Services organizations at `https://dev.azure.com/<organization>`. A trailing slash is accepted and removed when Kandev saves the canonical URL. Azure DevOps Server/TFS and alternate organization URL forms are not supported.
|
||||
|
||||
Enter the organization URL on the Azure DevOps settings page, then hover, focus, or tap the info icon beside **Personal Access Token**. Follow its **Create personal access token** link. In Azure DevOps, select **New Token**, choose the organization and an expiration, and select **Custom defined** scopes. Under **Work Items**, check **Read**; under **Code**, check **Read**; leave every other scope unchecked. Create the token, copy it while Azure DevOps still displays it, and paste it into Kandev.
|
||||
@@ -358,8 +383,13 @@ The **Remote** picker in **New Task** searches configured GitHub, GitLab, and Az
|
||||
|
||||
This release has no Entra OAuth flow, webhook, or watch poller.
|
||||
|
||||
</details>
|
||||
|
||||
## Jira
|
||||
|
||||
<details>
|
||||
<summary>Jira details</summary>
|
||||
|
||||
Jira configuration is workspace-specific. Use `/jira` to search with JQL, save views, open issue details, run supported transitions, and launch tasks with Jira prompt presets. Launch copies Jira URL/content into the task title and description; it does not store a durable Jira issue association on the task.
|
||||
|
||||
Enter the site URL (a missing scheme is normalized to HTTPS), choose **Cloud** or **Server/Data Center**, and optionally set a default project key. Authentication options are:
|
||||
@@ -382,8 +412,13 @@ The maximum in-flight value defaults to 5. Leave it blank for no cap. A cap defe
|
||||
|
||||
Deleting a Jira watch leaves its previously created tasks in place. **Reset** is destructive: after the preview, it permanently deletes every watch-created task, including archived tasks, clears cursor/deduplication state, and makes current matches eligible for the next poll.
|
||||
|
||||
</details>
|
||||
|
||||
## Linear
|
||||
|
||||
<details>
|
||||
<summary>Linear details</summary>
|
||||
|
||||
Linear configuration is workspace-specific. Enter a personal API key and optionally a default team. Kandev calls the fixed Linear GraphQL endpoint at `https://api.linear.app/graphql` and sends the key as its authorization value. Leaving the credential blank during an edit keeps the stored key.
|
||||
|
||||
After saving and testing the connection, use `/linear` to search by text, team, or assignee, view issue details, change supported states, and launch tasks. Linear launch uses fixed title/description construction, has no prompt-preset editor, and does not store a durable Linear issue association.
|
||||
@@ -394,8 +429,13 @@ Leaving the repository blank creates repo-less tasks. When a repository is selec
|
||||
|
||||
Linear polling is also bounded. **Default (Linear order)** reads one page of 50; an explicit dispatch sort reads at most five pages of 50 before sorting locally. Matches outside that window can remain unseen, and reset does not bypass the bound.
|
||||
|
||||
</details>
|
||||
|
||||
## Sentry
|
||||
|
||||
<details>
|
||||
<summary>Sentry details</summary>
|
||||
|
||||
Sentry configuration is workspace-specific and supports multiple named instances. This is useful when one Kandev workspace spans different Sentry organizations or self-hosted installations.
|
||||
|
||||
Create an instance with a unique name, base URL, and bearer authentication token. The default URL is `https://sentry.io`; replace it for self-hosted Sentry. A URL with no scheme becomes HTTPS. It must be a bare HTTP(S) host root—paths, queries, and fragments are rejected. The UI lists `org:read`, `project:read`, and `event:read` as the required read scopes.
|
||||
@@ -410,8 +450,15 @@ Each Sentry poll reads only the newest first page (up to 100 issues) and does no
|
||||
|
||||
An instance cannot be deleted while a watch references it. Because the instance binding is immutable, delete those watches first and recreate them against another instance if needed. Sentry issues appear in task issue-selection/current-task surfaces; there is no top-level `/sentry` browser comparable to GitHub, GitLab, Jira, or Linear.
|
||||
|
||||
</details>
|
||||
|
||||
## Slack
|
||||
|
||||
> **Security:** Slack matching text is untrusted input, and the external MCP endpoint exposes destructive task/configuration tools. Use a constrained utility agent and model; review the [external MCP security boundary](automation-and-mcp.md#external-mcp-security-boundary).
|
||||
|
||||
<details>
|
||||
<summary>Slack details</summary>
|
||||
|
||||
Slack support currently uses a browser-session polling connection. It is intended for a controlled personal workspace and is more fragile than OAuth or a bot installation. Kandev does not currently offer a Slack OAuth/bot install flow.
|
||||
|
||||
Configure, per workspace:
|
||||
@@ -436,8 +483,13 @@ Slack has no separate prompt editor. It uses the chosen Utility Agent's prompt f
|
||||
|
||||
Slack does not trigger on reactions, expose a slash command/shortcut, mirror task status, or provide a live chat bridge to a running coding agent. It searches matching messages rather than performing a one-time history import, which is why the first scan can process existing matches. Browser session credentials can expire without notice; reconnect when polling starts returning authentication failures. Turning off the browser-local **Enabled** switch does not stop the backend poller—remove the saved Slack configuration to stop it.
|
||||
|
||||
</details>
|
||||
|
||||
## Copy configuration between workspaces
|
||||
|
||||
<details>
|
||||
<summary>Copy configuration details</summary>
|
||||
|
||||
Supported integration pages offer **Copy configuration** with provider-specific behavior:
|
||||
|
||||
- GitHub copies repository scope, saved/default searches, and quick-action presets. It does not copy authentication or watches.
|
||||
@@ -447,6 +499,8 @@ Supported integration pages offer **Copy configuration** with provider-specific
|
||||
|
||||
Workspace automations are never copied by this action. Review the target workspace's repository and workflow scope before enabling any copied connection.
|
||||
|
||||
</details>
|
||||
|
||||
## Security and troubleshooting
|
||||
|
||||
Issue bodies, pull-request comments, commit messages, Slack threads, and incident details are untrusted prompt input. Use read-only credentials for triage, restrict repositories/projects/channels, and keep a human workflow gate before merge, release, deployment, or sensitive transitions.
|
||||
|
||||
@@ -8,6 +8,13 @@ status: experimental
|
||||
|
||||
Kandev ships example Kubernetes YAML in `k8s/`. It is a single-replica, persistent deployment example—not a Helm chart, operator, or supported high-availability topology. The release workflow publishes container images but does not apply these manifests to a cluster. Review and adapt every manifest before production use.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Pin a published image and keep one replica.
|
||||
2. Apply the ConfigMap, PVC, Service, and transformed Deployment.
|
||||
3. Port-forward first; add TLS and authentication before exposing an Ingress.
|
||||
4. Back up the database and PVC before upgrades or deletion.
|
||||
|
||||
## Architecture and limitations
|
||||
|
||||
The example creates:
|
||||
@@ -164,6 +171,11 @@ Use the SSL mode and trust material required by your database. PostgreSQL moves
|
||||
|
||||
## Agent execution in a pod
|
||||
|
||||
> **Docker boundary:** Do not add only a Docker socket mount. The runtime also needs helper, credential-session, and local-clone bind sources at matching daemon-host paths. Privileged Docker-in-Docker has a separate security and persistence model and no supplied manifest.
|
||||
|
||||
<details>
|
||||
<summary>Agent execution, resources, and probes</summary>
|
||||
|
||||
Local and Worktree profiles run agents inside the Kandev pod. Install agent CLIs from **Settings > Agents**, or derive an image that contains them. Runtime npm installs persist under `/data/.npm-global`. Choose the universal image when tasks need its additional build toolchains, but account for the larger image and non-root volume requirement.
|
||||
|
||||
The checked-in ConfigMap disables Local Docker. Do not add only a Docker socket mount: the current runtime also needs helper, credential-session, and local-clone bind sources to exist at identical paths on the Docker daemon host, and it currently selects a Linux/amd64 helper. See [containerized control plane limitation](docker.md#containerized-control-plane-limitation). A privileged Docker-in-Docker sidecar has a separate security and persistence model and no supplied Kandev manifest.
|
||||
@@ -197,6 +209,8 @@ startupProbe:
|
||||
|
||||
Tune from observed startup time. Keep readiness on `/health`; use separate external monitoring for dependencies and real workflows.
|
||||
|
||||
</details>
|
||||
|
||||
## Ingress and exposure
|
||||
|
||||
Kandev has no built-in user-auth boundary. Do not expose the example Ingress publicly until an authenticated gateway and TLS are in place.
|
||||
|
||||
@@ -9,6 +9,13 @@ Kandev can run as a desktop app, an interactive CLI process, an OS-managed servi
|
||||
|
||||
Kandev does not currently provide a user-login boundary for the web application, HTTP API, WebSocket, or external MCP routes. Treat anyone who can reach the backend as an operator. Keep it on a trusted host or private network, or put the entire origin behind an authenticated TLS reverse proxy.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Choose one process owner for the database and Kandev home.
|
||||
2. Check `/health` for readiness and **System > Status** for diagnostics.
|
||||
3. Back up the database and `master.key` before upgrades, resets, or recovery work.
|
||||
4. Preserve Git branches and external provider state separately from database backups.
|
||||
|
||||
## Choose an operating model
|
||||
|
||||
| Mode | Start and stop | Durable state | Update path |
|
||||
@@ -75,6 +82,11 @@ The supported SQLite layout for the System database and restore pages is the der
|
||||
|
||||
## Storage maintenance
|
||||
|
||||
> **Destructive:** **Force clear all** permanently removes eligible quarantine entries and discards their restore windows.
|
||||
|
||||
<details>
|
||||
<summary>Storage maintenance details</summary>
|
||||
|
||||
Open **Settings > System > Storage** to inspect Kandev-managed disk usage and configure cleanup.
|
||||
**Analyze** is read-only. **Run now** applies only the enabled cleanup rules and refuses to start
|
||||
while another maintenance run owns the cleanup gate. If task resources are active, the page names
|
||||
@@ -126,8 +138,15 @@ cleanup do not delete this legacy data by name or age. Remove it only through a
|
||||
host-administrator procedure after confirming that no live process references the target; stopping
|
||||
the Kandev service first provides the clearest maintenance boundary.
|
||||
|
||||
</details>
|
||||
|
||||
## Database operation
|
||||
|
||||
> **Single-owner rule:** SQLite uses one writer connection in WAL mode; only one Kandev backend should own the file. **Factory reset** is destructive and removes managed data after creating a pre-reset backup.
|
||||
|
||||
<details>
|
||||
<summary>Database operation details</summary>
|
||||
|
||||
### SQLite
|
||||
|
||||
SQLite is the default and is appropriate for a desktop, CLI, service, or single-replica container installation. Kandev uses one writer connection and a read pool in WAL mode. Only one Kandev backend should own the file.
|
||||
@@ -155,8 +174,13 @@ pg_dump --host "$PGHOST" --port "${PGPORT:-5432}" \
|
||||
|
||||
Switching `database.driver` does not migrate data. PostgreSQL and shared NATS remove two single-process data constraints, but they do not make Kandev horizontally scalable: WebSocket subscriptions, execution lifecycle/control state, and task workspaces remain process- or filesystem-local. The current product and supplied deployment validate one backend replica only; do not add replicas based on the database and event bus alone.
|
||||
|
||||
</details>
|
||||
|
||||
## SQLite backups
|
||||
|
||||
<details>
|
||||
<summary>Backup details</summary>
|
||||
|
||||
Open **Settings > System > Backups**.
|
||||
|
||||
1. Click **Create snapshot**. Kandev runs SQLite `VACUUM INTO`, including committed WAL frames, writes a temporary sidecar, then atomically renames it to `manual-<nanoseconds>.db`.
|
||||
@@ -178,8 +202,15 @@ kandev service start
|
||||
|
||||
Adapt the source for a custom `--home-dir`. This archive still does not include external PostgreSQL, remote executors, provider objects, or CLI credentials stored elsewhere in the operating-system home.
|
||||
|
||||
</details>
|
||||
|
||||
## Restore and recovery
|
||||
|
||||
> **Restore warning:** Stop or finish active sessions, relaunch Kandev after restoring, and reconcile worktrees, containers, pull requests, credentials, and other external state before restarting automation. A database restore does not roll those systems back.
|
||||
|
||||
<details>
|
||||
<summary>Restore details</summary>
|
||||
|
||||
### Restore a System snapshot
|
||||
|
||||
The supported UI flow applies to the default SQLite path:
|
||||
@@ -205,6 +236,8 @@ pg_restore --clean --if-exists --no-owner \
|
||||
|
||||
Restart one backend, allow schema initialization to complete, then validate it as a single-replica deployment. Match the restored data with a compatible Kandev version; Kandev has no automatic database downgrade or validated multi-replica operating path.
|
||||
|
||||
</details>
|
||||
|
||||
## Factory reset
|
||||
|
||||
In **Settings > System > Database**, click **Factory reset**, type `RESET`, and confirm. This is SQLite-only. The job:
|
||||
|
||||
@@ -27,6 +27,13 @@ Two more example plugins go deeper on specific surfaces:
|
||||
the host store, and opens kandev's real create-task dialog
|
||||
(`host.ui.TaskCreateDialog`) prefilled from a pull request.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Start from the plugin template.
|
||||
2. Implement the backend and manifest first.
|
||||
3. Add native UI, webhooks, or Host API capabilities only when needed.
|
||||
4. Run focused tests, package the plugin, and install it locally.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go (matching the version in `apps/backend/go.mod`).
|
||||
@@ -121,6 +128,11 @@ side effect.
|
||||
|
||||
## The Host API
|
||||
|
||||
> **Auth capability:** Only assert email addresses the identity provider verified as owned by the subject. An unverified or user-controlled email claim can take over an account; grant this capability only to trusted plugins.
|
||||
|
||||
<details>
|
||||
<summary>Host API and native UI details</summary>
|
||||
|
||||
A plugin calls back into kandev through the injected `Host`:
|
||||
|
||||
```go
|
||||
@@ -437,8 +449,13 @@ const handle = host.openModal({
|
||||
handle.close();
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Named slots
|
||||
|
||||
<details>
|
||||
<summary>Named slot details</summary>
|
||||
|
||||
`registerComponent(slot, Component)` injects a component into a host-defined
|
||||
slot. The host renders every plugin's component for that slot (each isolated
|
||||
behind an error boundary), so a slot may hold contributions from several
|
||||
@@ -683,6 +700,8 @@ combo conflicts with a core kandev shortcut, the core shortcut always wins —
|
||||
the plugin handler is skipped for that combo — and the conflict is surfaced
|
||||
in that same settings page so the user can rebind it.
|
||||
|
||||
</details>
|
||||
|
||||
## Three integration patterns
|
||||
|
||||
Both example repos are full, working plugins — read them rather than
|
||||
@@ -712,6 +731,9 @@ copy-pasting fragments:
|
||||
|
||||
## Packaging
|
||||
|
||||
<details>
|
||||
<summary>Packaging, publishing, and iteration</summary>
|
||||
|
||||
A plugin ships as `<id>-<version>.tar.gz`:
|
||||
|
||||
```
|
||||
@@ -821,3 +843,5 @@ Publishing](plugins-marketplace.md#publishing-a-plugin).
|
||||
it for you.
|
||||
|
||||
Related: [Plugins](plugins.md), [Plugin manifest reference](plugins-manifest.md).
|
||||
|
||||
</details>
|
||||
|
||||
@@ -12,6 +12,13 @@ optional UI bundle. Kandev parses and validates it **before any plugin code
|
||||
runs**. See [Authoring a plugin](plugins-authoring.md) for the build
|
||||
workflow and [Plugins](plugins.md) for install/operate.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Start from the annotated example.
|
||||
2. Set identity, version, runtime executable, and only the capabilities the plugin needs.
|
||||
3. Add config, webhooks, events, or UI fields only when the plugin uses them.
|
||||
4. Validate the manifest before packaging.
|
||||
|
||||
## Annotated example
|
||||
|
||||
```yaml
|
||||
@@ -75,6 +82,11 @@ ui: # optional native frontend plugin
|
||||
|
||||
## Field reference
|
||||
|
||||
> **Security:** `capabilities.auth` lets a plugin assert external login identities. Grant it only to trusted plugins whose identity provider verifies email ownership; a spoofed email claim can take over an account.
|
||||
|
||||
<details>
|
||||
<summary>Complete field reference and validation rules</summary>
|
||||
|
||||
| Field | Required | Type | Notes |
|
||||
|---|---|---|---|
|
||||
| `id` | yes | string | Must match `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, dots, underscores, hyphens; must start with a lowercase alphanumeric). Directory name under `~/.kandev/plugins/`. |
|
||||
@@ -264,3 +276,5 @@ they have no effect there and are overwritten on install:
|
||||
| `restart_count` | Best-effort restart bookkeeping used by the supervision loop. |
|
||||
|
||||
Related: [Plugins](plugins.md), [Authoring a plugin](plugins-authoring.md).
|
||||
|
||||
</details>
|
||||
|
||||
@@ -21,6 +21,13 @@ Like the rest of plugins, the marketplace ships in the base product with no
|
||||
feature flag to turn on — **Settings > Plugins** is always available in the
|
||||
sidebar.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Browse and filter the catalog.
|
||||
2. Select **Install** and review the package result.
|
||||
3. Update installed plugins only when you approve the new version.
|
||||
4. Add a team source only when you trust its maintainer.
|
||||
|
||||
> **Sideloading still works.** The marketplace only adds *discovery*. Installing
|
||||
> a plugin by URL or by uploading a `.tar.gz` is unchanged and always available,
|
||||
> even with every source disabled or offline — see
|
||||
@@ -99,6 +106,9 @@ Notes:
|
||||
|
||||
## Publishing a plugin
|
||||
|
||||
<details>
|
||||
<summary>Publishing details</summary>
|
||||
|
||||
Getting a plugin into the catalog follows a **one-repo-per-plugin** model,
|
||||
mirroring Obsidian's community-plugin registry: each plugin lives in its own
|
||||
public GitHub repository and publishes its package as a GitHub **Release**
|
||||
@@ -169,8 +179,13 @@ Ranking in the catalog is **GitHub stars only** — there is no download or usag
|
||||
telemetry to game. Full submission details are in
|
||||
[`plugin-registry/README.md`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/README.md).
|
||||
|
||||
</details>
|
||||
|
||||
## Host your own source
|
||||
|
||||
<details>
|
||||
<summary>Host-source details</summary>
|
||||
|
||||
You do not have to PR into the official registry to share plugins internally.
|
||||
Any URL that serves an `index.json` document of the catalog shape can be added
|
||||
as a marketplace source (see [Add a team or corporate
|
||||
@@ -191,3 +206,5 @@ shape, the build pipeline, and the source data model are specified in the
|
||||
Related: [Plugins](plugins.md), [Authoring a
|
||||
plugin](plugins-authoring.md), [Plugin manifest
|
||||
reference](plugins-manifest.md).
|
||||
|
||||
</details>
|
||||
|
||||
@@ -21,6 +21,13 @@ turn on: **Settings > Plugins** is always available in the sidebar. Because
|
||||
loaded plugin code runs with backend privileges, install only plugins you
|
||||
trust — see [Security posture](#security-posture).
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Open **Settings > Plugins**.
|
||||
2. Install from the marketplace, a URL, or a local tarball.
|
||||
3. Let the installer verify package integrity before it extracts or spawns the plugin; review the install result before enabling it.
|
||||
4. Disable or uninstall a plugin when it is no longer trusted or needed.
|
||||
|
||||
## How it works
|
||||
|
||||
|
||||
@@ -126,6 +133,9 @@ badge (`active`), a signing badge (`unsigned` today), and **Disable** and
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>Filesystem sideload and synchronization</summary>
|
||||
|
||||
## Filesystem sideload and Sync
|
||||
|
||||
Besides install-by-URL/upload, an operator with shell access to the host can
|
||||
@@ -153,6 +163,8 @@ At boot, kandev runs only the directory-sideload and missing-install steps
|
||||
already active. This is conservative by design: starting up never spawns a
|
||||
binary an operator hasn't explicitly approved via install or Sync.
|
||||
|
||||
</details>
|
||||
|
||||
## Enable, disable, uninstall
|
||||
|
||||
- **Disable** stops the subprocess. Config and state are preserved; no
|
||||
@@ -183,6 +195,9 @@ authenticated"). This is owner-scoped, so a plugin's card only ever appears on
|
||||
its own settings page. See [Named
|
||||
slots](plugins-authoring.md#named-slots) in the authoring guide.
|
||||
|
||||
<details>
|
||||
<summary>Package signing, storage, and security details</summary>
|
||||
|
||||
## Signed vs. unsigned packages
|
||||
|
||||
Every package's `checksums.txt` is verified at install time — this integrity
|
||||
@@ -207,6 +222,8 @@ identically to an unsigned one; signing is not required in v1.
|
||||
└── data/ # KANDEV_PLUGIN_DATA_DIR — shared across versions
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Security posture
|
||||
|
||||
- **Auth is the spawn relationship.** Kandev spawns the plugin subprocess
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Run and verify Kandev's version, runtime, desktop, container, npm,
|
||||
|
||||
Kandev uses one semantic version across the Git tag, native runtime bundles, desktop app, npm packages, GitHub release, container images, and Homebrew formula. Publish through the manual **Release** GitHub Actions workflow; do not update channels independently.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Choose one workflow mode.
|
||||
2. Verify `main`, checks, credentials, signing inputs, and affected targets.
|
||||
3. Run the release workflow and verify every published channel.
|
||||
4. Use backfill only to repair the latest release; publish a new patch for defective code or immutable artifacts.
|
||||
|
||||
## Choose the workflow mode
|
||||
|
||||
The workflow has four mutually exclusive operating modes:
|
||||
@@ -64,6 +71,9 @@ GHCR images are built before the GitHub Release. npm and Homebrew start only aft
|
||||
|
||||
Base image tags include `X.Y.Z`, `vX.Y.Z`, `sha-*`, and `latest`. Universal tags include `X.Y.Z-universal`, `vX.Y.Z-universal`, and the floating `universal`. The weekly universal rebuild updates only floating/dated weekly tags, never a version-specific release tag.
|
||||
|
||||
<details>
|
||||
<summary>Signing, verification, and partial-release recovery</summary>
|
||||
|
||||
## Signing and updater behavior
|
||||
|
||||
npm uses GitHub OIDC trusted publishers; there is no `NPM_TOKEN` release path. The main `kandev` package and all five `@kdlbs/runtime-*` packages publish provenance attestations. Homebrew requires its repository deploy key.
|
||||
@@ -131,3 +141,5 @@ Use `backfill_tag` only for the latest release when shipped source is correct an
|
||||
Publish a new patch instead when code is defective, an immutable npm package or version-specific image is wrong, manifests disagree, or repair would require changing tagged source. Never delete/reuse a published tag or move an npm version as a routine fix.
|
||||
|
||||
For implementation detail, inspect `.github/workflows/release.yml`, `.github/workflows/universal-rebuild.yml`, `scripts/release/`, `apps/cli/README_internal.md`, and desktop packaging scripts. Those files are automation source; this page is the contributor operating contract.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -9,6 +9,13 @@ This is a contributor guide for cloning, building, testing, and running the Kand
|
||||
|
||||
To operate the Kandev control plane on a remote host, use [Run as a service](run-as-a-service.md), [Docker](docker.md), or the experimental [Kubernetes guidance](k8s.md). To keep the control plane elsewhere and run agent tasks remotely, configure a Sprites or SSH [executor profile](executors.md). Those product paths do not use this guide's source bootstrap, development ports, `.kandev-dev` state, or test tooling.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Clone the repository in the disposable VM.
|
||||
2. Run `scripts/bootstrap-dev-env`.
|
||||
3. Start `make dev` and forward only the backend URL.
|
||||
4. Keep the VM, forwarded ports, credentials, and `.kandev-dev` state private.
|
||||
|
||||
## Before you start
|
||||
|
||||
You need:
|
||||
@@ -140,6 +147,9 @@ export AZURE_DEVOPS_EXT_PAT='...'
|
||||
|
||||
The Azure tooling is optional and only needed for Azure Repos operations. See [Git operations](git-operations.md#create-a-pull-request-or-merge-request).
|
||||
|
||||
<details>
|
||||
<summary>Development state, E2E, and executor limitations</summary>
|
||||
|
||||
## Development state and persistence
|
||||
|
||||
Normal `make dev` isolates state under `<checkout>/.kandev-dev/`, including its SQLite database, logs, task workspaces, and other Kandev home data. It does not use `~/.kandev` by default. The selected development profile uses embedded SQLite and the in-memory event bus, so PostgreSQL and NATS are not prerequisites.
|
||||
@@ -219,6 +229,8 @@ Local and Worktree executors run inside the development VM and need their agent
|
||||
|
||||
SSH and Sprites profiles still use their normal remote credentials and network paths. The fact that Kandev itself is already on a cloud VM does not convert a Local executor into a managed remote executor. See [Executors](executors.md#current-support).
|
||||
|
||||
</details>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `mise`, `node`, `go`, or `pnpm` is missing in a new shell
|
||||
|
||||
@@ -11,6 +11,13 @@ Install Kandev first using a persistent [CLI installation](cli.md#install). Do n
|
||||
|
||||
> **Network security:** the backend listens on `0.0.0.0` by default and ships with authentication **disabled**. Before allowing remote access, enable [opt-in authentication](authentication.md) (the **Authentication & users** feature toggle, or `KANDEV_FEATURES_AUTH=true`) and terminate TLS in a reverse proxy — authentication does not replace HTTPS. A server bound to non-loopback interfaces without authentication logs a startup warning. See [server configuration](configuration.md#root-and-server).
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Install Kandev persistently with the [CLI](cli.md#install).
|
||||
2. Choose a user service for one workstation or `--system` for boot-time service operation.
|
||||
3. Install, check `status`, and inspect `logs`.
|
||||
4. Keep the listener private or protect it with TLS, authentication, and an access proxy.
|
||||
|
||||
## Choose a service mode
|
||||
|
||||
| | User service (default) | System service (`--system`) |
|
||||
|
||||
@@ -9,6 +9,13 @@ Kandev is a developer workbench that runs agents with access to repositories, to
|
||||
|
||||
> Kandev does not currently provide a multi-user login, role-based access control, or an authorization boundary for its web UI, HTTP API, WebSocket, or external MCP routes. Treat anyone who can reach the backend as an operator with the potential to read or change developer data.
|
||||
|
||||
## Quick checklist
|
||||
|
||||
- Keep the backend on loopback or behind an authenticated TLS proxy.
|
||||
- Use Worktree, Docker, SSH, or Sprites only when their isolation boundary matches the risk.
|
||||
- Scope agent and provider credentials to the smallest repository and operation set.
|
||||
- Keep human approval before merge, release, deployment, or other irreversible actions.
|
||||
|
||||
## Choose a deployment boundary
|
||||
|
||||
| Use case | Recommended boundary | Avoid |
|
||||
|
||||
@@ -5,9 +5,13 @@ description: "Run named parallel agent sessions, inspect changes, review diffs,
|
||||
|
||||
# Sessions and Review
|
||||
|
||||
A session is one agent conversation on a task. A task can have several named sessions, but they all work in the same task environment and see the same repositories and branch state. Use extra sessions to split investigation, implementation, testing, or review. Give concurrent writers explicit file ownership because their edits are not isolated from one another.
|
||||
A session is one agent conversation on a task. Use it to direct work, inspect changes, and give precise feedback before you merge or ship. Concurrent sessions share the same task environment, so give each writer explicit file ownership.
|
||||
|
||||
The workbench combines agent chat with files, terminals, changes, the task plan, walkthroughs, and pull-request state. Treat those surfaces—not an agent's final message—as the evidence that work is complete.
|
||||
## Quick path
|
||||
|
||||
1. Start a session with a scoped prompt.
|
||||
2. Watch chat and tool activity; answer clarification or permission requests.
|
||||
3. Inspect the diff, run required checks, and send focused feedback until the change is ready.
|
||||
|
||||
## Start a parallel session
|
||||
|
||||
@@ -61,6 +65,9 @@ Stopping a turn does not itself run the next queued message. Expand the queue an
|
||||
|
||||
A CLI-passthrough profile displays the agent's native terminal interface in a PTY. It still belongs to the task, but it does not provide Kandev's structured chat messages and tool-call presentation.
|
||||
|
||||
<details>
|
||||
<summary>Let agents coordinate sessions</summary>
|
||||
|
||||
## Let agents coordinate sessions
|
||||
|
||||
Task MCP gives an agent three session-coordination operations:
|
||||
@@ -82,6 +89,8 @@ For urgent replacement work, the parent should use `message_task_kandev` with `d
|
||||
|
||||
Messages show peer attribution, and Kandev gives the receiving agent hidden reply instructions. The receiver can still decline the request. A full task UUID is sufficient for cross-workspace messaging, so treat task IDs as sensitive routing identifiers when untrusted agents share one deployment. See [Coordination](coordination.md) and [Automation and MCP](automation-and-mcp.md).
|
||||
|
||||
</details>
|
||||
|
||||
## Use the workbench
|
||||
|
||||
Desktop panel groups can host agent chat, files, terminals, Changes, the task plan, previews, and GitHub pull-request detail. Use **+** to add a panel. Mobile exposes sessions, files, terminal, and changes through task navigation and sheets. Its task switcher opens as an inset bottom card, and the current-session control shows the active agent's icon and name.
|
||||
@@ -207,6 +216,9 @@ GitHub has the complete in-app PR review path. A linked PR detail panel shows ch
|
||||
|
||||
GitLab has a provider-specific linked-MR panel. It shows overview and branch state, approvals and pipeline rollup, files, commits, reviewers, assignees, labels, and threaded discussions. It can add selected feedback to agent context, reply or resolve discussions, approve or unapprove, update people and labels, toggle MR notifications, merge, refresh, and unlink. GitLab permissions and project policy remain authoritative. See [Integrations](integrations.md#gitlab) for linking and watch limits.
|
||||
|
||||
<details>
|
||||
<summary>GitHub pull-request automation</summary>
|
||||
|
||||
### GitHub PR automation
|
||||
|
||||
The PR panel has two action controls:
|
||||
@@ -221,6 +233,13 @@ Open **Review follow-up** for three notification controls:
|
||||
|
||||
Lifecycle messages only report the observed event and canonical PR URL; the task workflow and agent context decide what to do next. The repair prompt comes from the built-in `ci-auto-fix` saved prompt and can be overridden for the task. These controls currently operate on GitHub-linked PRs, require the GitHub integration and repository permissions, and do not bypass provider policy. Azure PR creation returns a URL but does not supply the same linked checks, review, or automation panel. See [Integrations](integrations.md).
|
||||
|
||||
</details>
|
||||
|
||||
> **Confidentiality:** redaction is heuristic, a secret Gist is accessible to anyone with its URL, and the snapshot is rendered through a third-party service. Inspect the preview and do not share material that must remain private.
|
||||
|
||||
<details>
|
||||
<summary>Share a session externally</summary>
|
||||
|
||||
## Share a session
|
||||
|
||||
For an eligible structured-chat session, right-click its tab and select **Share**. Sharing is disabled only while the session is `CREATED` or `STARTING`; `RUNNING`, `IDLE`, `WAITING_FOR_INPUT`, `COMPLETED`, `FAILED`, and `CANCELLED` sessions can be shared. A running snapshot can become stale immediately.
|
||||
@@ -231,6 +250,8 @@ Inspect the full preview before publishing. Redaction covers common API-key patt
|
||||
|
||||
Use the same dialog to revoke a share. Revocation deletes the Gist and records it as revoked in Kandev.
|
||||
|
||||
</details>
|
||||
|
||||
## Completion checklist
|
||||
|
||||
Before moving a task to done:
|
||||
|
||||
@@ -5,7 +5,13 @@ description: "Create scoped tasks, configure workflow behavior, use plans, and m
|
||||
|
||||
# Tasks and Workflows
|
||||
|
||||
A task is the unit of work. A workflow is the ordered process that task follows. Keeping those two concerns separate lets the same repository use different processes for a quick fix, a planned feature, or a human-reviewed change.
|
||||
A task is the work to deliver. A workflow is the sequence of steps it follows. Use a task for the outcome and a workflow for the review process.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Add a repository to a workspace.
|
||||
2. Create a task with a clear outcome, a compatible agent, and an executor.
|
||||
3. Start the agent, review its changes, and move the task through the human gate.
|
||||
|
||||
## Understand the model
|
||||
|
||||
@@ -72,6 +78,11 @@ Kandev remembers draft or recently used repository, branch, executor, and profil
|
||||
|
||||
Creating a repository is available only in an unlocked, single-repository **New Task** form. Kandev rejects an existing target path, creates no initial files or commit, registers the repository in the workspace, and switches the task to a direct **Local** executor profile. If no direct Local profile is available, repository creation stays disabled. Add more repository rows only after selecting existing repositories; empty multi-repository worktrees are not supported.
|
||||
|
||||
> **Local changes:** creating a fresh local branch can discard dirty files only after explicit consent. Save or commit important work before approving it.
|
||||
|
||||
<details>
|
||||
<summary>Advanced task creation: agent-created tasks, long transcripts, multiple sources, and attachments</summary>
|
||||
|
||||
### Choose the profile for tasks created by agents
|
||||
|
||||
Open **Settings → General → Task Actions → Profile for Tasks Created by Agents** to choose which agent profile Kandev assigns when an agent calls a Kandev MCP tool that creates a task without choosing `agent_profile_id`. The profile determines the agent, model, and setup used when the new task starts:
|
||||
@@ -115,8 +126,13 @@ If Kandev cannot resolve a pasted remote URL or its branch, the repository row k
|
||||
|
||||
Changes and review are scoped by repository. State the expected deliverable, base branch, and pull-request target for every attachment. See [Coordinate work](coordination.md) for adding branches after creation and splitting multi-repository work.
|
||||
|
||||
</details>
|
||||
|
||||
### Add sources to an existing task
|
||||
|
||||
<details>
|
||||
<summary>Adding sources details</summary>
|
||||
|
||||
For a non-archived, repository-backed task, open the **Files** panel and choose **Workspace actions → Add Repositories to workspace**. Use **Add repository** to choose a workspace repository, an existing local Git checkout, or a provider-backed/pasted remote URL. The workspace option shares task creation's saved/discovered selector, refresh, and create-repository actions. Use **Add folder** for an arbitrary local folder when the executor supports it. Add one or more rows in a single submission. Repository rows choose a base branch once; the flow does not ask for a second checkout branch. Local/Local PC uses the user-owned repository's current checkout and never switches it. The whole mixed batch succeeds or fails together.
|
||||
|
||||
The task must be idle: Kandev disables the action while a turn or tool call is active, and rejects a race without changing the task. Desktop opens a dialog; phones open the same flow in a full-height drawer. On success, repositories appear in Files and repository-aware Changes, branch, editor, and pull-request surfaces; folders are Files-only.
|
||||
@@ -145,6 +161,8 @@ The task prompt supports image, audio, and resource attachments. The backend acc
|
||||
|
||||
Creating a fresh local branch is available only with the local executor. If the checkout is dirty, Kandev lists the affected paths and requires explicit consent before discarding those local changes. If another path becomes dirty after the warning, creation fails with a conflict and asks for consent again. Save or commit work before approving this operation.
|
||||
|
||||
</details>
|
||||
|
||||
## Start a task
|
||||
|
||||
A task created with **Create without starting agent** opens in a prepared workbench. Review its repository, branch, executor, profile, and initial prompt, then select **Start agent**. The run stays in the task conversation, where environment preparation, tool calls, permission requests, and the final response remain inspectable.
|
||||
@@ -188,6 +206,9 @@ On phones, Kanban focuses one workflow and one step at a time. The board navigat
|
||||
|
||||
Regular Kanban does not currently expose label editing or label filters. Do not design a supported Kanban process around labels.
|
||||
|
||||
<details>
|
||||
<summary>Configure a workflow, its steps, automation, and human gates</summary>
|
||||
|
||||
## Configure a workflow
|
||||
|
||||
Open **Settings → Workspaces → _workspace_ → Workflows**, then open a workflow card. A workflow has a name, an optional **Default Agent Profile**, and ordered steps. When the workflow has a default profile, users cannot choose another profile in the task-creation dialog.
|
||||
@@ -269,6 +290,8 @@ An entry action can auto-start an agent, and turn completion can move the task i
|
||||
|
||||
For examples and portability, see [Workflow tips](workflow-tips.md), [Workflow import and export](workflow-import-export.md), and [Workflow sync](workflow-sync.md).
|
||||
|
||||
</details>
|
||||
|
||||
## Use the task plan
|
||||
|
||||
Regular tasks have one shared Markdown plan, not a collection of named documents.
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Choose and run Kandev's Go, web, CLI, script, PostgreSQL, Playwrig
|
||||
|
||||
Use the narrowest test that proves a rule, then cover the real boundary when behavior crosses a process, protocol, database, executor, or user journey.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Start with `make fmt`, `make typecheck`, `make test`, and `make lint`.
|
||||
2. Run the focused package or Vitest test for the changed rule.
|
||||
3. Add Playwright coverage for every `apps/web/` behavior change.
|
||||
4. Run PostgreSQL, container, real-agent, or desktop layers only when the change crosses that boundary.
|
||||
|
||||
## Standard local checks
|
||||
|
||||
From the repository root, format first:
|
||||
|
||||
@@ -5,7 +5,14 @@ description: "Install Kandev, add a repository, configure an agent, run a first
|
||||
|
||||
# Get Started with Kandev
|
||||
|
||||
This guide establishes the smallest useful Kandev setup: one local Git repository, one coding-agent profile, the built-in Worktree executor profile, and the default Development workflow.
|
||||
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
|
||||
|
||||
@@ -39,6 +46,9 @@ By default, persistent state is under `~/.kandev`, including the SQLite database
|
||||
|
||||
See the [CLI reference](cli.md) for commands, port and logging flags, data paths, environment variables, and update behavior. Other supported entry points are the [desktop app](desktop-app.md), [service](run-as-a-service.md), and [Docker deployment](docker.md). Read [Security and trust](security.md) before making any installation remotely reachable.
|
||||
|
||||
<details>
|
||||
<summary>First-run records and onboarding details</summary>
|
||||
|
||||
## Know what a fresh database contains
|
||||
|
||||
Kandev creates these records when no prior workspace or executor configuration exists:
|
||||
@@ -51,6 +61,8 @@ Kandev creates these records when no prior workspace or executor configuration e
|
||||
|
||||
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.
|
||||
|
||||
</details>
|
||||
|
||||
## Add a local repository
|
||||
|
||||
1. Open **Settings > Workspaces > Default Workspace > Repositories**. If you created or renamed the workspace, choose that workspace instead.
|
||||
@@ -127,6 +139,9 @@ See [Sessions and review](sessions-and-review.md) for the workbench and [Tasks a
|
||||
|
||||
Use the [Security and trust](security.md) guide to choose a local, remote, shared-team, or unattended-automation boundary and to review the deployment checklist.
|
||||
|
||||
<details>
|
||||
<summary>Troubleshoot a task that will not start</summary>
|
||||
|
||||
## Troubleshoot a task that will not start
|
||||
|
||||
Check in this order:
|
||||
@@ -147,3 +162,5 @@ Common corrections:
|
||||
- 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](operations.md). For release-specific disagreement, record the version from **Settings > System > About** and compare it with the matching GitHub tag.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Develop Kandev's Vite/React routes, domain data flow, settings, wo
|
||||
|
||||
`apps/web/` is a React 19 single-page application built by Vite. In production, the Go backend serves its output and remains the API, WebSocket, and authorization boundary.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Run `make dev` and use the printed URLs.
|
||||
2. Trace the route through `src/spa-routes.tsx` or `src/settings-routes.tsx`.
|
||||
3. Put requests in the owning domain client/hook and live updates in the WebSocket handler.
|
||||
4. Test loading, error, reconnect, keyboard, desktop, and mobile states before review.
|
||||
|
||||
## Run the application
|
||||
|
||||
```bash
|
||||
|
||||
@@ -25,6 +25,13 @@ The source of truth is the combination of:
|
||||
|
||||
An action constant alone is not evidence that an action is registered or emitted. The request catalog below was checked against non-test `RegisterFunc` calls and the gateway's special subscription dispatch, not just the constant list.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Prefer the UI, CLI, MCP tools, or documented HTTP routes for supported integrations.
|
||||
2. If you need the WebSocket, connect to `/ws` and send one JSON request per frame.
|
||||
3. Correlate responses by `id`, refetch after reconnects, and treat notifications as invalidation hints.
|
||||
4. Protect the endpoint: it has no client authentication boundary.
|
||||
|
||||
## Security and network boundary
|
||||
|
||||
The current `/ws` upgrade handler does **not authenticate clients**. It reads `?token=` or the `Authorization` header but does not validate or use the value; JWT validation is still a code TODO. The default backend host is `0.0.0.0`, so a default process can listen on every interface even though examples use `localhost`.
|
||||
@@ -246,6 +253,9 @@ websocat ws://127.0.0.1:38429/ws
|
||||
|
||||
`websocat` is a third-party diagnostic dependency, not bundled with Kandev. Remember that an originless tool is accepted only because the current endpoint trusts its network boundary.
|
||||
|
||||
<details>
|
||||
<summary>Registered actions and emitted notifications</summary>
|
||||
|
||||
## Registered request action catalog
|
||||
|
||||
The following 310 unique action names have concrete dispatcher registrations in the current backend. The 12 subscription/focus actions in the previous table are additional gateway-handled requests. Availability can still depend on a configured integration, handler mode, or service; registration does not supply credentials, provider installation, a running executor, or permission to external systems.
|
||||
@@ -783,6 +793,8 @@ File changes are batched for up to 100 ms and flushed immediately at 50 entries.
|
||||
|
||||
Routing is an efficiency mechanism, not an access-control boundary. The server does not authenticate resource ownership, global messages can contain IDs for other workspaces, and a client can request arbitrary subscription IDs.
|
||||
|
||||
</details>
|
||||
|
||||
## Reconnect and troubleshooting
|
||||
|
||||
- **Upgrade returns 403:** inspect the browser `Origin` and proxy `Host`. The hostnames must match exactly or both be loopback; ports may differ. A scheme other than `http`/`https` or an origin containing a path is rejected.
|
||||
|
||||
@@ -7,6 +7,13 @@ description: "Run Kandev on Windows through native and WSL workflows."
|
||||
|
||||
Kandev has native Windows x64 desktop and npm/npx releases. WSL 2 remains useful when repositories, agents, or setup scripts assume a Linux environment. Choose one execution environment per Kandev installation; a native process and a WSL process use different filesystems, tools, Docker endpoints, and credential stores even when they can reach each other over localhost.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Choose Desktop or the native npm/npx CLI for normal Windows use.
|
||||
2. Use WSL 2 only when Linux tools or scripts are required.
|
||||
3. Keep repositories, agents, Docker, and credentials in the same environment as Kandev.
|
||||
4. Use the troubleshooting section for path, shell, and browser differences.
|
||||
|
||||
| Path | Best for | Main limitations |
|
||||
|---|---|---|
|
||||
| [Desktop app](./desktop-app.md) | Normal interactive use, native menus/notifications/updates | Windows x64 and WebView2; no service/background mode |
|
||||
@@ -125,6 +132,9 @@ docker info
|
||||
|
||||
The local Docker executor creates its client lazily, so Kandev can start even when Docker Desktop is stopped; the executor fails when first used and retries on a later attempt. Windows drive sharing, bind mounts, corporate Docker policies, and WSL-backed Docker Desktop are external dependencies. Do not expose an unauthenticated Docker TCP endpoint. See [Docker](./docker.md).
|
||||
|
||||
<details>
|
||||
<summary>Run Kandev in WSL 2</summary>
|
||||
|
||||
## Run in WSL 2
|
||||
|
||||
WSL is the better choice when the repository's commands and agent CLI are Linux-native.
|
||||
@@ -170,6 +180,8 @@ Keep Linux worktrees in the WSL filesystem (for example under `~/src` or the def
|
||||
|
||||
When Docker Desktop WSL integration is enabled for the distribution, verify `docker info` inside WSL. Otherwise install/configure a Linux Docker daemon inside WSL according to your platform policy. Native Windows named-pipe settings do not apply inside WSL; its default endpoint is the Unix socket.
|
||||
|
||||
</details>
|
||||
|
||||
## Remote executor limitation
|
||||
|
||||
The release bundle carries remote `agentctl` helpers for Linux `amd64`/`arm64` and macOS `amd64`/`arm64`. It does not carry a Windows remote helper. Consequently, a Windows desktop/CLI host can control supported Linux/macOS SSH targets, but a Windows machine is not a supported destination for the SSH executor. Remote Docker behavior depends on the target daemon and configured Linux container image; it does not add a Windows `agentctl` remote target.
|
||||
|
||||
@@ -9,6 +9,13 @@ Kandev's versioned portable format moves Kanban workflow definitions between wor
|
||||
|
||||
Use this for snapshots and one-time copies. Use [Workflow Sync](workflow-sync.md) when a GitHub repository should remain the source of truth.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Export a regular Kanban workflow from **Settings > Workspaces > Workflows**.
|
||||
2. Copy or save the YAML.
|
||||
3. Import it into the destination workspace.
|
||||
4. Review profile mapping and skipped names before using the workflow.
|
||||
|
||||
## Use the UI
|
||||
|
||||
Open **Settings → Workspaces → select a workspace → Workflows**.
|
||||
@@ -19,9 +26,14 @@ Open **Settings → Workspaces → select a workspace → Workflows**.
|
||||
|
||||
Export does not download a file or change the workflow. Import creates new workflows; it never overwrites a same-named workflow. Delete an unwanted imported workflow through the normal workflow settings flow.
|
||||
|
||||
> **Network security:** The HTTP routes are unauthenticated. Keep the backend on loopback or behind an authenticated, origin-protected reverse proxy before exposing them to a network.
|
||||
|
||||
<details>
|
||||
<summary>HTTP format, fields, and reconciliation details</summary>
|
||||
|
||||
## HTTP routes
|
||||
|
||||
All routes are on the Kandev backend under `/api/v1`. The current backend does not authenticate these routes, so treat anyone who can reach them as trusted to read or create workspace workflows. Keep the backend on loopback or put it behind an authenticated, origin-protected reverse proxy before exposing it to a network.
|
||||
All routes are on the Kandev backend under `/api/v1`.
|
||||
|
||||
| Method | Route | Behavior |
|
||||
|--------|-------|----------|
|
||||
@@ -166,8 +178,15 @@ The runtime model also has `on_comment`, `on_blocker_resolved`, `on_children_com
|
||||
|
||||
The Workflows settings UI filters Office-style workflows from its list and Export All selection for this reason. Manage Office workflow behavior through its product surface; do not use portable Kanban import/export as an Office backup.
|
||||
|
||||
</details>
|
||||
|
||||
## Profile matching
|
||||
|
||||
> **Import warning:** Validation happens before creation, but import is not one transaction across the file. A later failure can leave partial workflows or steps; inspect the workspace and delete incomplete workflows before retrying.
|
||||
|
||||
<details>
|
||||
<summary>Profile matching and import details</summary>
|
||||
|
||||
Profile IDs are installation-specific, so the portable descriptor stores values:
|
||||
|
||||
```yaml
|
||||
@@ -251,6 +270,8 @@ workflows:
|
||||
|
||||
After import, assign a workflow-level or Work-step agent profile if the destination did not produce an exact portable profile match. Create a disposable task, verify Backlog → Work pulling, the WIP rejection at capacity, explicit completion, and Review feedback before adopting it.
|
||||
|
||||
</details>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **`unsupported export version/type`:** keep `version: 1` and `type: kandev_workflow` exactly.
|
||||
|
||||
@@ -9,6 +9,13 @@ Workflow Sync makes a GitHub directory the source of truth for selected workflow
|
||||
|
||||
Choose sync when workflow changes should be reviewed and versioned in Git. Choose [Workflow Import / Export](workflow-import-export.md) for a one-time copy that remains editable in Kandev.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Put portable workflow YAML in a GitHub repository.
|
||||
2. Grant the workspace connection read access.
|
||||
3. Select the repository, branch, and directory in **Workflows > Sync**.
|
||||
4. Run a sync and review created, updated, skipped, and removed definitions.
|
||||
|
||||
## Prerequisites and credentials
|
||||
|
||||
You need a GitHub repository and a branch containing valid portable workflow files. The Kandev backend—not the browser and not a task executor—reads the repository. The workspace automation connection must therefore have contents-read access to the configured branch, including for private repositories, and the repository must be inside the workspace's effective scope.
|
||||
@@ -102,9 +109,14 @@ A valid fetch that returns no supported files is different: it is an empty desir
|
||||
|
||||
Repository listing or file-download failures fail the run before apply. Per-workspace locking serializes sync, configuration changes, and removal, so two requests cannot interleave their changes.
|
||||
|
||||
> **Network security:** The HTTP API is unauthenticated and can read or change sync configuration with the backend's GitHub credentials. Keep the backend on loopback or behind an authenticated, origin-protected reverse proxy before exposing it.
|
||||
|
||||
<details>
|
||||
<summary>HTTP API, reconciliation, and cleanup details</summary>
|
||||
|
||||
## HTTP API
|
||||
|
||||
The settings UI uses these backend routes. All require a `workspace_id` query parameter. They currently have no backend authentication: any network client that can reach them can inspect or change sync configuration and trigger repository reads with the backend's GitHub credentials. Keep the backend on loopback or put it behind an authenticated, origin-protected reverse proxy before exposing it.
|
||||
The settings UI uses these backend routes. All require a `workspace_id` query parameter.
|
||||
|
||||
| Method | Route | Success behavior |
|
||||
|--------|-------|------------------|
|
||||
@@ -140,6 +152,8 @@ Choose **Remove sync** to stop polling. Kandev first clears GitHub ownership fro
|
||||
|
||||
Deleting an individual repository definition has the different reconciliation behavior described above. Move or archive tasks first when you intend the corresponding synced step or workflow to disappear.
|
||||
|
||||
</details>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Authentication error:** run `gh auth status --hostname github.com` in the backend environment or configure one of the token sources above. Confirm that identity can read the repository and branch.
|
||||
|
||||
@@ -13,6 +13,13 @@ Workflow prompts run with the selected executor's filesystem, credentials, and n
|
||||
|
||||
> Workflow definitions can be copied between workspaces with [Workflow Import / Export](workflow-import-export.md), or reconciled from a repository with [Workflow Sync](workflow-sync.md).
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Start with **Kanban** for ordinary task tracking.
|
||||
2. Choose **Plan & Build** or **PR Review** when the workflow itself should guide the agent.
|
||||
3. Add automatic starts only when the executor, profile, and prompt are ready.
|
||||
4. Keep a human **Review** or **Do nothing** gate before risky changes ship.
|
||||
|
||||
## Built-in Kanban templates
|
||||
|
||||
The template prompts are product behavior, not merely sample text. Review them before using a template in a repository with strict Git, test, or deployment rules. Kandev currently presents these five Kanban templates.
|
||||
@@ -111,6 +118,9 @@ Pull candidates are selected by board position, then priority, queue time, creat
|
||||
|
||||
## Events and actions
|
||||
|
||||
<details>
|
||||
<summary>Events and action details</summary>
|
||||
|
||||
The standard Kanban editor exposes these events:
|
||||
|
||||
| Event | When it runs | Editor actions |
|
||||
@@ -124,8 +134,15 @@ The portable format also recognizes `set_session_mode`, `clear_decisions`, `queu
|
||||
|
||||
Keep one transition action per event. A “next” action on the last step or “previous” on the first has nowhere to go and leaves the task in place. WIP rejection, a missing target step, a failed agent launch, or missing credentials can also prevent the intended progression; inspect the task/session error and backend logs before changing the workflow.
|
||||
|
||||
</details>
|
||||
|
||||
## Safe authoring pattern
|
||||
|
||||
> **Safety:** Requiring `step_complete_kandev` can leave a step waiting indefinitely if the agent cannot call it. Export before large edits; workflow deletion is permanent and may require task migration or archival.
|
||||
|
||||
<details>
|
||||
<summary>Safe authoring details</summary>
|
||||
|
||||
1. Start with manual transitions and verify prompts in a disposable task.
|
||||
2. Add `auto_start_agent` only to steps that always have an effective agent profile.
|
||||
3. Add turn-complete transitions after the prompt has an unambiguous stop condition.
|
||||
@@ -133,8 +150,13 @@ Keep one transition action per event. A “next” action on the last step or
|
||||
5. Add WIP limits before pull rules, then test a full target and a vacated slot.
|
||||
6. Export the workflow before a large edit. Workflow deletion is permanent; when it contains tasks, the UI asks you to migrate them or archive them.
|
||||
|
||||
</details>
|
||||
|
||||
## Saved prompt references in step prompts
|
||||
|
||||
<details>
|
||||
<summary>Saved prompt reference details</summary>
|
||||
|
||||
A step's Prompt field accepts `@name` references to [saved prompts](developer-tools.md#saved-prompts) (**Settings > Prompts**), the same way task chat does. Type `@` and select a prompt, or type the name directly.
|
||||
|
||||
- The reference is resolved when the step prompt runs, not when it is saved. Editing the saved prompt's content later automatically changes what every step referencing it sends next time — there is nothing to update on the step itself.
|
||||
@@ -143,12 +165,19 @@ A step's Prompt field accepts `@name` references to [saved prompts](developer-to
|
||||
|
||||
The same `@name` syntax and resolution apply to a GitHub Review Watch's prompt field. See [Integrations](integrations.md#configure-and-use-the-workspace).
|
||||
|
||||
</details>
|
||||
|
||||
## Repository instructions and multiple repositories
|
||||
|
||||
<details>
|
||||
<summary>Repository instruction details</summary>
|
||||
|
||||
Step prompts are combined with the selected agent and the checked-out repository. Keep repository-specific instructions such as `AGENTS.md`, `CLAUDE.md`, skills, test commands, and MCP configuration in that repository. Kandev does not make one repository's agent rules automatically authoritative for another.
|
||||
|
||||
A task may contain several repositories, but a workflow step is not bound to one repository. The agent session receives the task workspace and its repository set. Prompts should name the intended repository when the phase is repository-specific, and Git operations must be scoped per repository. See [Git Operations](git-operations.md).
|
||||
|
||||
</details>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Task starts in the wrong column:** confirm exactly one Start step, save the workflow, and check whether the creator supplied an explicit `workflow_step_id`.
|
||||
|
||||
Reference in New Issue
Block a user