Agents and Profiles

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

Open Settings > Agents (/settings/agents). Kandev scans the host on which its backend runs, not the browser computer.

The production registry currently shows Auggie, Claude, Codex, Copilot, Gemini, OpenCode, Amp, Qwen, iFlow (beta), Droid, Kilocode, Pi, Cursor, Kimi, Kiro, Qoder, Trae, omp, Devin, Grok, Hermes, Goose, and Antigravity. An entry is usable only when its executable is supported on the current platform and available to the Kandev process. Development and E2E profiles can add mock agents that are not product integrations.

Hermes launches with hermes acp. Install the required hermes executable from its Settings > Agents card, which runs the official Hermes installer. Hermes currently supports task and workspace sessions. Office-assigned skill injection is not yet supported.

Goose launches with goose acp. Its Settings > Agents card runs only the official download_cli.sh installer. Homebrew (block-goose-cli) and pip (pip install goose-ai) are manual alternatives. Configure your model provider with goose configure. Goose currently supports task and workspace sessions.

Antigravity has no automated install: Google distributes agy_acp_server.par (agy_acp_server.exe on Windows) and its localharness_external or localharness sibling (localharness_external.exe or localharness.exe on Windows) as a signed archive through the ACP registry rather than npm, so extract both files into one directory and add it to PATH yourself. Kandev fails discovery closed when the harness sibling is missing or not executable, so a partial extraction reports as not installed rather than as a broken session.

Pi command surfaces

Pi uses separate executables for its two Kandev modes:

• Structured ACP sessions and one-shot inference use npx -y pi-acp.
• CLI Passthrough starts the globally installed pi executable.
• The Pi install action runs npm install -g --ignore-scripts @earendil-works/pi-coding-agent.

After installation, select Rescan. Kandev detects Pi when pi is on the PATH of the backend process and responds to the non-interactive --version check. The pi-acp adapter is not the interactive terminal CLI, and managed ACP runtime selection does not replace the passthrough command.

1. Select Rescan after installing or updating a CLI.
2. If the card offers an install action, review the command before running it. Installation runs on the Kandev host.
3. If the card reports that login is required, open its login terminal or authenticate the CLI as the same operating-system user that runs Kandev.
4. Open the seeded default profile and review it before selecting the agent in a workflow step or session. Discovery creates one default profile the first time it provisions an agent. If you deliberately delete every profile, later rescans do not recreate one; create a replacement manually.

The status shown on this page is authoritative for the current host. A CLI that works in your interactive shell can still be absent from Kandev when the service has a different PATH, home directory, or operating-system user.

Update a managed agent runtime

The update icon is available on managed Claude, Codex, OpenCode, Copilot, and Gemini agent cards. It updates the runtime on the Kandev host.

Each managed runtime has a reviewed Kandev default. If you have not selected a version, Kandev uses that exact default for probes, sessions, standalone inference, containers, and SSH commands. A successful version update stores your exact selection for this Kandev installation. The selection takes precedence for the current default generation. Use Kandev default clears it, and a later shipped package or reviewed default resets it during startup. Kandev does not store the default as a user selection.

When a Kandev upgrade changes the managed package or its reviewed default, Kandev removes the older selection during startup before the service becomes ready. New probes and launches then use the reviewed default for that release. On the first startup with this generation tracking, Kandev treats an existing selection without a generation marker as legacy and resets it once. When the package and default stay the same, Kandev preserves your selection across restarts and unrelated upgrades. A process that is already running is not replaced, so the new default applies when Kandev starts a future process.

After startup, open the update control to select any validated stable version, including an older version. This lets you roll back the new default when a provider or environment requires it. The selection remains active until you change it or a later Kandev release changes that agent's package or default.

When the cached npm check finds a newer stable release, the update control has a blue dot and its accessible label includes the effective and latest versions. The dot is only a hint. Opening the control performs a fresh, authoritative preview before any update starts. If the check is unavailable, the control has no dot but remains usable.

1. Select the update icon.
2. Review the current version, active version, available stable versions, and command.
3. Keep the latest version selected for a normal update, or select an older stable version to roll back.
4. Select Update runtime, Roll back runtime, or Repair runtime.
5. Wait for the exact version to prepare and pass its ACP capability probe.

Kandev enables the action only after the backend validates the selected version against the trusted package catalogue. It does not accept package names, npm tags, prereleases, registry URLs, or command text. When the active version, observed version, and target version match, the action is disabled as Up to date. A successful activation updates the advertised models, modes, configuration options, commands, and runtime version without a page reload.

• The active exact version survives Kandev and browser restarts.
• Later host-local probes, utility calls, and standalone sessions use the active exact version.
• Active sessions keep running. They are not restarted or hot-swapped.
• Passthrough agents and authentication helpers remain unchanged. The Settings update job prepares the host runtime only; remote executor and new-container commands still use the effective exact version and must resolve that package in their own environment. Running sessions and containers are unchanged.
• If preparation, ACP validation, authentication, or persistence fails, Kandev keeps the previous active version and capability catalogue. Select another stable version or retry the same target.
• Kandev may prepare the exact version again if npm removes its cache entry. Kandev does not own an offline package inventory, and global npm cache cleanup is not required.

Recover a stale npm runtime lookup

Host-local managed runtimes normally start with npm's offline-preferred lookup. If npm has stale package metadata and cannot resolve the selected package@version, the first ACP startup can fail even though the configured registry contains that exact version. Kandev recognizes this specific npm resolution error, removes only the deterministic _npx execution tree for the selected package and version, then retries the same command once with an online-preferred metadata lookup.

Kandev also performs this recovery while it builds the host capability catalogue used by agent profiles. A successful retry publishes the recovered models and keeps the saved model, fallback model, mode, runtime version, and enabled state unchanged. The profile remains selectable and does not show a capability warning. Kandev reports a failed capability status if it cannot prepare the retry or repair the cache, or if the one online retry fails.

The same recovery applies to managed runtime startup on a local PC, in a local Docker executor, or in a remote SSH executor. Kandev sends the repair request to the agentctl process that owns the failed execution. That process resolves npm's cache with the agent environment and removes only the selected execution tree. It does not repair the Kandev host cache, delete sibling execution trees, change the registry, or clear the global npm cache.

The retry keeps the selected package, exact version, command prefix, model, permissions, and session identity. It does not change the npm registry or silently select another version. When the retry succeeds, no recovery card is shown. When it fails again, Kandev and Office show one Retry runtime action with collapsed technical details.

Do not use npm cache clean --force as the normal recovery step. It removes unrelated npm data and does not target the stale execution tree. If the specialized retry cannot resolve the runtime, check that the Kandev service uses the expected npm installation and configured registry. Run npm config get registry as the Kandev service user to inspect the registry used by that process. Then use the runtime update controls to select and prepare another trusted stable version.

Add a custom terminal agent

Add a custom terminal agent

Use Settings > Agents > Add TUI Agent for a CLI that Kandev does not register. Enter a display name, command, and optional model label. {{model}} in the command is replaced by the selected model value, then the entire command is split on whitespace with Go's strings.Fields.

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.

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.

Model, mode, command, and configuration choices are probed from the locally installed CLI and cached. The managed Update agent action refreshes them automatically; after other CLI changes, refresh the profile manually. Probe status can report auth required, not installed, not configured, or failed; a saved model name does not prove that the current provider account can use it.

Configuration options are resolved for the model selected in the profile. An agent can therefore show a different option set for each model. If a model change makes a saved option value unsupported, Kandev removes that value after a successful resolution; a failed resolution keeps the draft unchanged so you can retry it.

Model IDs and executor catalogs

The host model probe is an editing hint. The selected executor owns the model catalog at launch. Kandev resolves a saved model in this order:

1. Use the exact requested model when the executor advertises it.
2. Use the advertised explicit fallback when the requested model is absent.
3. Use one unique bracketed variation when the requested model is absent and the executor advertises exactly one matching ID.
4. Use the agent's current or default model when no earlier choice applies.

Profiles with automatic fallback enabled keep the legacy behavior when the saved model is absent: Kandev ignores the explicit fallback and does not infer a variation. It uses the agent's current or default model instead.

For example, a saved opus model can launch as opus[1m] when that is the only advertised opus[...] ID. If the executor advertises both opus[270k] and opus[1m, fast], Kandev does not choose either variation. Variation text is opaque and model IDs remain case-sensitive.

Kandev shows a warning when the launch result differs from the saved model. The saved profile remains opus; Kandev does not rewrite it after applying a unique variation or using the agent default. Recheck the executor catalog when the warning repeats after credentials, copied configuration, or agent updates.

Use a dynamic profile

Choose the Dynamic agent family when you create a profile. Add concrete profiles in the order that Kandev must try them. The logical dynamic profile stays selected in the task and utility binding, while each launch uses one concrete candidate behind the scenes. Candidates must be enabled, launchable profiles. Dynamic profiles and rich Office profiles cannot be candidates.

Use the Dynamic agents card at the top of Settings > Agents to create and list dynamic profiles. The card is hidden, and dynamic profiles cannot be selected for new work, when dynamic routing is disabled. A new profile starts with its name and candidates; enable or disable it later from the profile editor.

Each candidate has a policy for two shared provider-error classes:

• Transient errors include capacity, overload, network, timeout, rate, and provider-availability failures.
• Hard errors include authentication, subscription, quota, credit, model, and provider-configuration failures.

For each class, configure exponential same-candidate retries, the maximum retry count, the initial interval, reset-date waiting with a maximum wait, and the final Skip candidate or Stop for manual recovery outcome. Kandev uses a trusted future reset date at most once for a candidate and class when it fits the configured maximum. It then applies the retry schedule and outcome. Unclassified, task, repository, permission, tool, and ambiguous mid-turn failures stop for manual recovery so Kandev does not repeat work. The error catalogue is versioned and can grow as provider signals become known; an ambiguous new signal fails closed. A future classifier may improve catalogue coverage, but no model is called to classify errors today.

After a provider switch, the failed provider is paused for the route health backoff, or until its trusted reset time when one is available. Kandev runs an exclusive health probe before it becomes eligible again. This shared error classification is used by task/Kanban and Office routing, while the per- candidate policies are configured on dynamic profiles.

Provider errors that occur before a result can use the configured action, such as retrying the current candidate or trying the next candidate. A started turn with an ambiguous result does not switch providers automatically. If no candidate is eligible, the session waits for a recovery action. After the current turn settles, use Retry current agent or Try next agent in the session recovery surface. These actions use the current route generation, so a stale browser action does not replace a newer route decision.

Host probes and executor model catalogs

The model list shown while editing a profile comes from a host probe. It is an editing hint, not a launch gate. A profile remains selectable when its saved model is missing from that host list.

At task launch, the selected executor's ACP catalog is authoritative. For profiles without automatic fallback, Kandev follows the four-step order above. For profiles with automatic fallback enabled, an absent saved model causes no model request, and Kandev ignores the explicit fallback and any variation. Kandev stores one warning in task chat with the requested model and the effective model when known. The warning also identifies the agent and executor and asks you to check credentials, copied configuration, and the agent version.

The saved profile model is not changed. Optional portable configuration can copy selected allowlisted files into a remote executor, but it cannot guarantee that the host and executor expose the same model catalog.

Monitor capability and subscription status

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.

Office agent quota and provider usage

Monitor Office agent quota

When Office mode is enabled, open Office > Agents and select an Office agent to see its Subscription Quota on the overview; the Office dashboard also summarizes the highest utilization across subscription agents. These cards appear only for supported subscription agents with provider credentials.

For account-wide provider usage across supported providers, install the Provider Usage plugin. It adds a provider pill to the session top bar and can add a compact display to the global status surface. That surface is off by default and follows the portable Show status bar preference under Settings > Preferences > Appearance > Status Bar; saving applies without a restart. If it is off, the session top-bar pill remains available. When it is on, the plugin can also appear in the desktop/tablet bottom bar or phone Status drawer. Configure the plugin under Settings > Plugins > Provider Usage. These usage surfaces are operational signals, not a billing ledger or a guarantee that the next request will be accepted; provider availability, account policy, and concurrent usage still apply.

CLI flags and ACP command prefixes

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.

The field is not a shell script. Pipes, redirects, variable expansion, and command substitution do not run as shell syntax. Empty or malformed quoting is rejected. Keep separate profiles for materially different permission or workspace flags, and recheck customized flags after upgrading the CLI.

Claude CLI passthrough uses standard output by default. Add an enabled --verbose entry to the profile CLI flags when you need diagnostic output.

Some older profiles contain compatibility fields such as Auggie's allow_indexing; current launch behavior is represented by the active profile settings and flags.

ACP command prefixes

Command prefix is available for ACP launches, not terminal-passthrough launches. Kandev parses the prefix into structured argv rather than running a shell: quote a path containing spaces, for example "/opt/launchers/safe wrapper" --. The resulting argv is prefixed to the agent command, so shell features such as pipes, redirects, variable expansion, and command substitution are not evaluated.

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.

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.

Kandev has two secret scopes:

• Global secrets are available to the current user across their workspaces. When authentication is disabled, Global is install-global.
• Workspace secrets belong to one workspace and can be selected by that workspace's repositories. They are not available to shared agent or executor profiles.

The General page manages Global secrets. Manage Workspace secrets from Settings > Workspaces > workspace > Secrets. Agent and executor profile selectors intentionally show Global secrets only; a Workspace reference saved through an older or direct API path is rejected when the profile is saved or launched.

Copy or move a secret between scopes from the Copy/Move action on any secret row. The dialog picks Copy or Move, chooses a destination (Global or another workspace), and lets you edit the target name; it is pre-filled as <name> (from Global) or <name> (from <workspace name>) so copied secrets keep their origin visible. Moving removes the original after the copy is safely in place, and the value is transferred server-side between encrypted rows. It is never shown or copied through the browser. A target name that already exists in the destination blocks the action until you rename it.

Kandev encrypts secret values at rest with AES-256-GCM. The encryption key is <KANDEV_HOME_DIR>/data/master.key (by default ~/.kandev/data/master.key) and is created with owner-only file permissions. KANDEV_DATABASE_PATH does not relocate this key. Protect and back it up with the Kandev database; losing it makes stored values unreadable. Anyone with access to the Secrets settings can reveal the plaintext.

Profile environment rules are:

• at most 100 entries;
• key length at most 256 characters and value length at most 8,192 characters;
• keys cannot contain = or a NUL character, and values cannot contain NUL;
• duplicate keys are rejected;
• TASK_DESCRIPTION and every KANDEV_* key are reserved;
• an entry must use either a literal value or a secret reference, never both.

Kandev resolves secret references at process launch and cold resume. A deleted, missing, or unreadable secret blocks launch before the agent starts. The error identifies the environment key and its source.

Secret deletion is blocked while an agent profile, executor profile, or repository environment references the secret. When you select Delete, Kandev checks first. If the secret is in use, a dialog lists the affected resources and does not offer a delete action. Remove or replace those references before deleting the secret.

If a reference is already broken, open the named profile and select the replacement secret for the affected key, save, and retry. For a visible repository reference, open that repository's environment settings and replace the binding. A redacted repository reference means the repository is in a workspace that you cannot access; a workspace user with edit permission must locate and replace the binding in that workspace's repository settings. If no such user exists, ask a workspace owner or administrator to grant access or repair the binding. Creating a secret with the same name does not repair the reference because each secret has a separate ID.

API clients can explicitly force deletion. This leaves broken references and blocks future launches until those references are repaired. See the secret deletion API contract.

Repositories can bind an environment key to a Global secret or to a Workspace secret from the same workspace under Settings > Workspaces > workspace > Repositories. A task inherits bindings from every attached repository. Repository bindings are secret references, never values, and a repository binding to a deleted or unreadable secret blocks that task's launch. If two sources provide the same key, Kandev deduplicates an identical secret reference and rejects every other collision; repository order never chooses a winner.

Literal values remain in profile configuration. A secret reference avoids copying a token there, but the selected agent and its child processes still receive the plaintext at runtime. Use narrowly scoped credentials, and keep read-only review profiles separate from profiles allowed to publish, merge, deploy, or administer external systems.

Permissions and unattended work

In a structured ACP session, the agent can present a permission request and its available responses. With Auto-approve all permissions disabled, a person chooses a response in the session. With it enabled, the runtime selects the first allow-once or allow-always response without waiting. If the agent supplies no allow response, Kandev selects its first response even when that response is not approval; with no responses, it cancels.

An external MCP client can also list live pending requests for an authorized task and submit one exact option originally offered by the agent. The request-generation ID prevents an old approval from targeting a replacement prompt that reused a provider pending ID. Kandev records who selected which option before delivery and rejects concurrent or replayed answers. It does not expose hidden environment values, headers, raw MCP arguments, or option metadata. See Resolve a live agent permission request.

Auto approval can authorize shell commands, file changes, network calls, or any other capability exposed by that agent. Agent-specific flags that suppress permission prompts can be broader still. Use either only with a constrained executor, repository, environment, and credential set.

Workspace automation selectors do not offer passthrough agent profiles. Local executor profiles are available for the repository-free target; Worktree requires a repository. Hidden automation sessions receive a fixed workspace-scoped coordinator MCP surface. Visible normal-task automations use the ordinary task profile and MCP surface. The trusted automation principal is resolved before hidden-run dispatch, and a hidden automation task and its sessions cannot be used as mutation, messaging, stopping, spawning, or blocker targets. Cross-task spawning uses the target task's normal profile. Native provider continuation and compaction remain authoritative for a healthy reusable session; Kandev's fallback resume prompt uses only the newest 50 non-empty user or assistant messages and excludes tool events. See Automation and MCP.

Structured ACP and terminal passthrough

ACP sessions can expose typed messages, tool updates, permission requests, models, modes, dynamic configuration, todos, usage, and resume metadata. Each capability depends on the agent's actual ACP implementation. ACP-only profile settings, including command prefixes and structured configuration, do not add those capabilities to a terminal-passthrough CLI.

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.

Configure external MCP servers

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.

Supported server types are stdio, http, sse, and streamable_http. If type is absent, a command implies stdio and a url implies http. Connection mode can be:

• auto: per-session for stdio and shared for a network transport;
• per_session: create a connection for each agent session;
• shared: reuse a network connection. Stdio cannot use shared mode.

The built-in task-aware server is injected separately. A profile server named kandev is ignored so it cannot replace the task server.

Executor policy can allow or deny transports or server names, rewrite URLs, and inject environment values. In the current launch wiring, profile MCP resolution starts from the standalone allow-all baseline for every executor and then overlays the selected executor profile's explicit MCP policy. A blank SSH, Sprites, or other remote policy therefore inherits allowed stdio, HTTP, SSE, and streamable HTTP transports; it does not receive the deny-all remote default defined elsewhere in the runtime. Set an explicit restrictive executor MCP policy before relying on remote isolation.

MCP JSON, including headers and server env, is stored as profile configuration. The raw editor has no secret-reference field for those values, so do not paste long-lived credentials into it unless access to the profile store is an acceptable boundary. Prefer a server that can inherit a narrowly scoped profile environment secret.

Passthrough injection adds CLI-specific exposure. Codex encodes MCP environment values and HTTP headers into -c process arguments, which another local user may read through process inspection. Cursor and Pi write project-local .cursor/mcp.json or .pi/mcp.json; when either file already exists, Kandev merges its entries and deliberately does not remove them at teardown because it does not own the user's file. Review and remove persisted entries or credentials yourself.

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.

Delete profiles and custom agents

Deleting a profile is irreversible. Kandev checks references before deletion:

• active sessions and watcher references are soft conflicts; force bypasses the active-session check and soft-deletes the profile, while disabling affected watchers is best effort rather than guaranteed cleanup;
• enabled automations bound to the profile are disabled before it is deleted, and a failure to disable them aborts the deletion. Unlike watchers, an automation has no preflight that would notice a profile had vanished, so it would otherwise keep firing at a profile that no longer exists;
• feature-flagged Office routing-tier references are hard conflicts and cannot be forced;
• Kandev attempts to clean every ephemeral task with a session using the profile, including matching Quick Chat and Configuration Chat. A cleanup failure is logged and does not prevent profile deletion, so audit leftover resources afterward.

Only custom TUI agents can be deleted from the agent list. Built-in definitions remain registered even when their CLI is not installed.

Troubleshooting

• Agent unavailable after install: confirm the executable as Kandev's service user, select Rescan, and compare the service PATH with your shell.
• Login required: use the agent card's login terminal or sign in under Kandev's operating-system user; signing in as another user does not help the service.
• Model, mode, or command probe fails: authenticate first, refresh discovery, and choose a value advertised by the installed version.
• Launch fails after editing flags: inspect the command preview, remove stale arguments, and correct unmatched quotes or trailing escapes.
• Managed npm runtime cannot resolve its selected version: Kandev checks the configured registry and retries the same version once after refreshing its exact _npx execution tree. If the retry fails, verify the service user's npm configuration and registry, then use Settings > Agents to prepare another trusted stable version. Do not start with npm cache clean --force.
• Environment value is absent: confirm the secret still exists, the key is not reserved, and an executor/runtime variable is not already taking precedence.
• MCP server is absent: confirm agent MCP support, valid JSON, transport mode, executor policy, and the session warning logs.
• MCP tools are missing from one agent session: open MCP servers in that session's chat toolbar. Select kandev, then find the tool in the scrollable list. Select the tool to inspect its description, token estimate, and arguments. Use Back to tools, then Back to servers on touch devices. Connected means the built-in server completed MCP initialize. Active means it served tools/list. A gray row explains an intentional omission. Red identifies an explicit sanitized error. Delivered, connection unverified applies to a profile server that connects directly to the agent. Kandev cannot inspect that server's tools. Inspect the affected session because each report belongs to one session and execution.
• Automation cannot select a profile: passthrough agent profiles and Local executor profiles are intentionally omitted from the automation selectors.

Related: Executors, Automation and MCP, and the contributor guide Adding a new agent CLI.