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.

The composer model picker shows the session's agent CLI logo beside the selected model and beside Model in the open popover. This identifies the CLI running the session, even when it supports models from several vendors.

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.

Agent page options

On Settings > Agents, select Options beside Terminal to open Agent options. Turn on Hide disabled profiles from navigation to remove disabled profiles from the Settings navigation tree. Disabled profiles remain available on the Agents page, and the preference applies immediately in this browser profile.

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, Muse, Antigravity, and MiniMax. 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.

Codex app-server (experimental)

Kandev offers Codex app server as a separate native Codex profile. It uses the Codex app-server protocol, while Codex ACP continues to use the ACP bridge. Existing sessions keep their original agent identity.

Enable Codex app server in Settings > System > Feature Toggles, then restart Kandev. The toggle is off by default and requires a restart. The native profile is hidden from new-session selectors while the toggle is off. Keep it enabled while native sessions need to resume.

Kandev currently uses @openai/codex version 0.154.0 as its managed default. Sign in to Codex as the operating-system user that runs Kandev, or provide OPENAI_API_KEY to the executor. The profile uses the same workspace and MCP configuration as other structured sessions.

Native sessions show response and turn token usage in the chat footer. A provider thread usage estimate may appear when Codex reports one. It is an estimate, not a promise of the billed charge. Kandev keeps provider estimates separate from calculated cost.

After a completed turn, use Fork conversation to create another session through that turn. The new session keeps the task and executor, and files remain shared in the workspace. It does not create a branch or worktree. Native Codex subagents and background commands stay within the session; they do not become separate Kandev tasks.

Codex questions sent through Kandev's ask_user_question_kandev MCP tool or through the native app-server item/tool/requestUserInput method use the normal clarification UI. Native options and permitted free-text answers map back to Codex's answer format. Secret questions fail closed because Kandev's clarification flow stores answers in the conversation. If Codex resolves a pending request, Kandev closes the corresponding clarification.

MiniMax Code

MiniMax uses the official MiniMax Code CLI directly through mcode acp. Install it from Settings > Agents > Browse, or install the tested release with npm:

npm install -g @minimax-ai/code@0.5.10 --registry=https://registry.npmjs.org/ --ignore-scripts=false --include=optional --allow-scripts=@minimax-ai/code,better-sqlite3
mcode --version

Use a supported Node.js version (22.19+ in the 22 series, 24.2+ in the 24 series, or 25/26). The optional SQLite dependency and its installation scripts must be allowed. Kandev reports MiniMax installed only when mcode is on its PATH and responds to --version; npm alone does not count as an installation.

Sign in as the operating-system user running Kandev. For a mainland China account use mcode login --no-browser; for a Global account use:

env -u MINIMAX_DATA_DIR -u MAVIS_DATA_DIR \
  -u __MAVIS_RUNTIME_DATA_DIR -u __MAVIS_RUNTIME_PROFILE \
  mcode login --region global --no-browser

Choose Mainland China or Global when Kandev opens the login setup. The selected login terminal prints a browser authorization link. Close an existing sign-in terminal before choosing a different region in another tab. After login, click Done to refresh capabilities, create a MiniMax profile, and choose a model from the native catalog. Subscription access stays with MiniMax Code; no OpenCode wrapper or static API key is required.

Native catalog entries currently include MiniMax-M3, M3.1-Flash-Preview, MiniMax-M2.7-highspeed and MiniMax-M2.7. Available models and thinking variants come from your CLI/account and may change. The native defaults for the two M3 models are 512k context, with an optional 1M window; M2.7 models use 200k. These are upstream catalog values, not guaranteed account entitlements. MiniMax's ACP interface currently accepts text prompts and does not advertise image, audio or video inputs, even when the underlying model supports media.

Kandev retains the native ACP provider/model/variant identifiers in profiles. CLI passthrough translates them into --model provider/model#variant and uses --session <id> or --continue for resume. Structured sessions use ACP model selection, permission requests, MCP configuration, cancellation and session load. Kandev does not add a MiniMax permission bypass flag.

MiniMax owns its config, subscription credentials and sessions under ~/.minimax. Kandev's native integration targets that default directory and removes MINIMAX_DATA_DIR, MAVIS_DATA_DIR, __MAVIS_RUNTIME_DATA_DIR and __MAVIS_RUNTIME_PROFILE from agent launches and POSIX login. If you already use a named MiniMax profile or a custom data directory, sign in to the default directory for this integration. MiniMax's installation directory ~/.minimax-code is separate from its data directory.

The login terminal requires a POSIX host shell. On native Windows, sign in with mcode login --no-browser outside Kandev after clearing the four data/profile override variables above from that shell. Otherwise login can target a directory that Kandev's ACP runtime does not use.

Containers persist an isolated .minimax directory at /root/.minimax. Remote/container executors need their own installation and native login inside that environment. Kandev does not copy host OAuth tokens: native credential records include the absolute auth-directory identity and cannot be treated as portable credentials. No provider or account fallback is injected on failure.

Claude Code and Codex CLI version and model discovery

For Claude and Codex, the agent card shows the installed vendor CLI's version next to the detected path (for example "Claude Code 2.1.220" or "Codex CLI 0.155.1"), or a muted "version unknown" line with a short reason when the version command fails or times out. Reinstalling or upgrading through the card's install action re-detects the version automatically, without a backend restart.

The profile editor's Start model dropdown includes suggestions from the host CLI. The Codex CLI publishes a model list (codex app-server), so its dropdown shows that list merged with the models the running session already advertises, and a note under the selector states the source and CLI version. The Claude Code CLI does not publish a model list, so the dropdown keeps the session's list and the note says so. For both agent types you can type any model ID as a free-text entry, useful the day a vendor ships a model (for example a new Opus release) before Kandev's own build catches up. A profile's saved model that is missing from every list still shows up as a selectable entry with its exact identifier, and saving without changing it leaves it unchanged. Whether the running session actually accepts a typed identifier is up to that session; an identifier it does not recognize fails with its own error at the start of the next turn, the same as for a listed model.

The Codex catalogue can be bundled or cached by the CLI. Listing a model does not confirm account entitlement or availability in a profile that uses a different command, configuration, or executor. The profile's capability probe and the selected executor still determine whether that model can run.

Muse command surfaces

Muse Code has no native ACP server, so Kandev runs it through the community @bex-co/muse-code-acp adapter, which is not affiliated with Meta:

• Structured ACP sessions and one-shot inference use the managed @bex-co/muse-code-acp package at the selected effective version. This needs Node.js 22 or later.
• The adapter drives the native muse executable through muse serve; CLI Passthrough starts muse directly.
• On POSIX hosts, the Muse install action runs the official https://dev.meta.ai/install.sh installer into the first writable directory on the backend's PATH. Windows has no automated Muse install action because the official installer is a POSIX shell script.

Kandev detects Muse when muse is on the PATH of the backend process and responds to --version. Sign in with muse login, or set META_API_KEY for headless and remote executors. Muse keeps sessions under ~/.local/share/muse, which Kandev uses for session resume. Kandev removes XDG_CONFIG_HOME and XDG_DATA_HOME overrides from Muse processes so credentials and sessions use these managed paths. Executors use an isolated home directory for both ~/.config/muse and ~/.local/share/muse; the real host home directory is not mounted.

The adapter starts sessions on the model in Muse's ~/.config/muse/settings.json and falls back to its own default otherwise, while the interactive muse CLI falls back to Meta's catalogue default. To pin one model for both, set it there, for example {"schema_version": 1, "model": "muse-spark-1.3"}.

Pi command surfaces

Pi uses separate executables for its two Kandev modes:

• Structured ACP sessions and one-shot inference use the managed pi-acp package at the selected effective version.
• 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 Oh My Pi on the Kandev host

On an installed omp card, select the update icon under Settings > Agents. Review the installed version, the Stable latest (reference) version, and the omp update command, then choose Update runtime or Repair runtime. Kandev runs OMP's own updater as the Kandev service user on the host, streams its output, and refreshes ACP capabilities only after a successful probe. Active sessions are not restarted.

OMP detects whether its installation is managed by Homebrew, mise, Bun, npm, or a standalone binary and updates through that method. A Nix-managed installation cannot be updated by this action. OMP follows its already configured stable or canary channel; Kandev does not choose a channel or pass a version to omp update. The stable latest shown in Settings is a comparison reference, not a promised install target: the installed version reported by OMP after updating may differ. There is no version picker, Kandev pin, or rollback for OMP.

The update affects only the host installation, not task containers or remote executors. If OMP's updater or the follow-up ACP probe fails, Settings reports the error and retains the previous capability catalogue; Kandev cannot restore an executable that OMP already changed. When metadata is unavailable, the update icon remains available, but a preview must resolve the stable reference before the update can start.

Update a managed agent runtime

The update icon is available on managed Claude, Codex, OpenCode, Copilot, Gemini, Pi, and Muse agent cards when Kandev owns their managed runtime. It prepares their pinned npm runtime on the Kandev host. OMP uses the separate self-update flow above.

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 runtime capability probe.

OpenCode has two runtime families. Fresh Kandev installations use the managed v2 package @opencode/cli. Kandev keeps an existing v1 selection on opencode-ai until you choose the v2 migration action.

Move OpenCode from v1 to v2

Use this action only after you review the shared-data boundary. OpenCode v1 and v2 use the same configuration and session data paths.

1. Stop standalone OpenCode v1 processes that use the same session data.
2. Open the OpenCode update control in Settings > Agents.
3. Select Upgrade to managed OpenCode v2 and review the package, version, and scope.
4. Select Upgrade to managed OpenCode v2 again to start the upgrade.
5. Keep Kandev open while it installs the package and checks ACP startup.

The selection applies to future OpenCode launches across every OpenCode profile in this Kandev installation. This includes local, container, and SSH executors. The action installs the managed v2 package; it leaves a standalone opencode installation unchanged.

Kandev saves v2 as the active runtime only after the exact package passes an isolated ACP probe. Kandev-owned active OpenCode work blocks activation. The upgrade does not stop that work. If the probe or database write fails, v1 remains selected. If capability discovery fails after activation, v2 remains selected and Kandev reports the discovery error.

Kandev keeps saved OpenCode session IDs when it restores a conversation. If OpenCode cannot restore a saved conversation, Kandev reports the error in that session. It does not create a replacement conversation. Kandev cannot reverse changes that OpenCode v2 makes to shared session data, so selecting v1 later does not guarantee a rollback.

When an existing native OpenCode v1 installation remains selected, same-family updates can still update that native executable. A v2 migration always uses the managed @opencode/cli package and does not run a global npm install.

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.

When a native OpenCode installation is present on the host, its vendor update guidance stays separate from Manage fallback versions. That control selects the managed package used by remote and container launches; it does not update the native host or a remote native installation. Update, rollback and return to the Kandev default remain available for the managed fallback. A rejected or busy manual request leaves automatic-update consent unchanged; an accepted manual selection turns it off.

Recover a managed runtime startup failure

Managed runtime startup can retry once when npm reports a strict ETARGET for the selected exact package or a recognized temporary network or cache error. The ETARGET retry prefers an online lookup. Kandev can also retry an ordinary process exit before ACP initialization when complete, generation-matched startup evidence confirms that stderr was empty. Incomplete evidence, other permanent or unrecognized npm errors, cancellation, signal termination, and failures after ACP initialization do not trigger this automatic retry. Kandev first confirms that the failed process has stopped, then waits two to three seconds before the replacement starts.

The retry uses the same agent, package, exact version, environment, executor, session, and initial prompt. It does not delete the selected npm execution tree or a sibling tree. While it waits, the existing session status shows the second attempt. If that attempt succeeds, the conversation continues without a recovery card. If it fails, the card reports the cause and actual attempt count and shows one Retry runtime action with collapsed technical details.

This startup recovery applies to managed npm runtimes on a local PC, in a local Docker executor, or in a remote SSH executor. It does not establish that an npm race caused any particular startup failure. Host capability discovery has a separate, narrower recovery: an exact-package ETARGET result can retry once with an online-preferred lookup. That probe retry also preserves npm execution trees and keeps the saved model, fallback model, mode, runtime version, and enabled state unchanged.

Managed npx runtimes use a Kandev-owned npm project directory, so an .npmrc in the task repository does not change the managed runtime's package lookup. The task repository remains the command's working directory. User and global npm settings still apply, including min-release-age and before policies. If an age policy blocks the selected version, Kandev does not repair the npm cache or repeat the lookup online. Wait until the version meets the policy, or select an older trusted version, then choose Retry runtime.

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.

Refresh profile models after a runtime update

Manage runtime versions in Settings > Agents > Agent runtime updates. Profile pages focus on model selection and launch settings.

After a managed runtime update succeeds, an open profile refreshes its model catalog with the current draft settings. The selected model stays unchanged. Unsaved launch settings remain unsaved. A failed update keeps the previous catalog.

After you edit launch settings, choose Refresh models to check the current draft. The provider returns the model catalog. Discovery success does not confirm catalog completeness or account access to every model.

Runtime notifications and automatic updates

Kandev checks enabled, available agent runtimes in the background, including native CLIs with a verified release source. Open Settings > Agents to review runtime versions and update policies. A notice for one runtime names it and links directly to its row in Settings > Agents > Agent runtime updates. The existing update-available notification preferences apply; repeated notices for the same runtime and version are suppressed across reloads.

At startup or after reconnect, available runtime updates discovered within the same 30-second window appear in one summary. Review updates opens the expanded runtime section. A notice for one runtime keeps its name and direct link. Update success, failure, and interruption notices remain individual and immediate.

The Agent runtime updates section is at the bottom of Settings > Agents, after your installed agents, and starts collapsed. Expand it to manage runtime policies. Notification links open the section automatically and reveal their destination. Collapsing the section preserves unsaved policy changes.

The runtime section shows the selected or observed version, latest known version, and who manages the installation. Unknown means Kandev could not verify the version or release source. It does not mean the runtime is up to date. Unavailable and disabled registrations remain listed separately, without background checks. Offline and source failures do not create error notifications.

Automatic updates are off by default. An administrator can enable Automatic updates for each eligible managed runtime, then select the shared Save changes action. This consent applies to the Kandev installation and survives reloads. Kandev checks on startup and every 15 minutes; successful release lookups are cached for six hours and failed lookups for 15 minutes.

An automatic update prepares a stable exact version and validates it before activating it for future launches. Running sessions keep their existing process and version. The retained result records the old and target versions. If preparation, validation, or activation fails, that attempt preserves the previous selection. Kandev reports the failure and does not repeatedly retry that target. An interrupted update has an unconfirmed result; review the current selection before retrying.

Use Manage versions to retry manually, choose an older stable version, or return to the Kandev default. A manual version choice turns off automatic updates, so Kandev does not undo your choice. Disabling automatic updates also prevents a candidate still being prepared from activating. To retry automatically after a failure, turn the option off and save, then turn it on and save again.

Externally managed npm packages and native CLIs show Manual update guidance when vendor documentation is available. Their supported vendor or package-manager updates remain owned by the operator. Kandev does not infer update authority from PATH or run an unverified global updater. Custom commands, virtual agents, and other runtimes without a supported updater explicitly show the unsupported state.

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.

On Settings > Agents, administrators can reorder an agent's profiles using its drag handle with a pointer or touch. For keyboard control, focus the handle, press Space to pick up the profile, use the arrow keys to move it, and press Space again to save (or Escape to cancel). The order is saved for that agent, shared with other open Settings pages, and used in the Settings navigation tree. Creating or duplicating a profile places it first in that agent's Settings list.

This order applies only to Settings. Task creation, in-task agents, handoff, and other profile selectors keep their existing option order, contextual recency, and default selection.

Agents can inspect and update declared profile settings through the compact search_settings_kandev, describe_setting_kandev, get_settings_kandev, and update_settings_kandev tools. Use the separate agent_profile_mcp target for the profile MCP document. The settings tools preserve profile validation and save replacement lists atomically. They never return environment values or MCP credentials; use references or the existing interactive credential flow when a secret is required.

Model and mode choices are probed from the locally installed CLI. Opening a saved concrete profile probes its saved environment, CLI flags, and command prefix. If you edit any of these launch settings, select Refresh models before you choose a model. Kandev probes the current draft without saving it or sending a prompt. A secret reference is resolved on the Kandev host and its value is not sent back to the browser. Probe status can report auth required, not installed, not configured, unsupported, or failed; a saved model name does not prove that the current provider account can use it.

Use an OpenAI-compatible provider

Open the Provider section in a profile that supports this feature. Select OpenAI-compatible provider, enter the absolute router base URL, and select an optional global API-key secret. Enter the model ID that the router accepts. The model field is free text because the router owns the model catalogue.

Kandev sends the provider URL and optional bearer key through the ACP gateway authentication request when a new process starts. A running process keeps its existing provider settings until it restarts. CLI passthrough cannot use this provider because that path does not run the ACP authentication handshake.

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.

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 by default. The optional repeated-failure policy below is a narrow exception for eligible, current, effect-safe unclassified failures. 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.

Dynamic profiles also have an API-only option for repeated, safe unclassified failures. It is off by default and is not exposed in the profile editor. In a candidate's policies object, set unclassified to:

{
  "enabled": true,
  "consecutive_failure_threshold": 3
}

When enabled, the threshold must be an integer from 2 to 10. Configure the field through POST /api/v1/agents/dynamic/profiles or PATCH /api/v1/agent-profiles/:id, along with the candidate's existing transient and hard policies. An omitted or disabled policy does not count failures; a disabled policy must use a threshold of 0.

Kandev counts only a current task-session failure that has complete trusted evidence and no output or tool activity. Eligible errors are a terminal unknown_provider_error before output, or a typed agent process-start or session-initialization agent_runtime_error. For provider errors, each counted failure must have the same code, origin, phase, provider, and complete diagnostic. Kandev normalizes whitespace only; case and punctuation remain significant. Diagnostics that need redaction or truncation stay on manual recovery. Task, repository, permission, tool, cancellation, ambiguous mid-turn, stale, and other unclassified failures also remain manual.

Below the threshold, each failure stops for manual recovery. Use Retry to make the next attempt; there is no automatic retry timer. On the threshold failure, Kandev tries the next enabled candidate in order, without wrapping to an earlier candidate. If no next candidate is eligible, recovery remains manual. The count resets when a failure is unsafe or different, when the candidate, profile, policy, or workflow step changes, or after a successful turn. This extension applies to task sessions. Office runs and utility calls remain outside its scope.

Any workflow step can veto this policy with disable_unclassified_fallback: true. The field is available through the workflow-step API and is included in workflow import/export. The veto applies to the step's task session even when the candidate policy is enabled.

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.

When a task launch waits for session capacity, Kandev keeps the selected destination and retries it automatically. Inspecting another session does not change the workflow's selected step or primary session. You can open another session and use its normal controls. Kandev resumes it when the session can run; the automatic session ceiling still applies unless you explicitly start, resume, or message the session.

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. Profile selectors show an amber warning icon for this difference. On a desktop pointer, hover or focus the icon to read its tooltip. On a touch device, select the icon to open its warning drawer. Inspect the model list in profile settings for discovery details. Authentication, installation, and probe-failure indicators remain visible on profile selectors.

At task launch, the selected executor's ACP catalog is authoritative. Kandev sends the requested model only when the executor advertises it. Profiles are compatible by default, so an unavailable saved model can use an advertised explicit fallback, one unique bracketed variation, or the executor's current or default model. Kandev records one warning with the requested and effective models when it continues with a different model. Automatic fallback allows provider-default continuation and ignores the saved explicit fallback.

Enable Require exact model when the profile must keep the saved model. The executor must advertise and accept that model before the first prompt. An empty or unsupported catalog, an unavailable model, or a failed apply stops the session before inference. Kandev never sends an unadvertised model and never rewrites the saved profile model.

For Auggie ACP task sessions, Kandev also requires the selected model and mode to take effect before it sends the first prompt. If a failed session offers the explicit recovery Resume action, it keeps the same conversation and skips saved mode and model overrides for that attempt only. Saved profile and session settings remain unchanged, and later ordinary starts or resumes enforce them again. See Manage session state for the recovery notice and resolved or dismissed history in Chat.

The host model list is only an editing hint. A missing host-probe model keeps a profile selectable and shows an advisory warning; the executor catalog decides the launch result. Upgrades and omitted API fields keep existing profiles compatible, with strictness off until a user enables it. Optional portable configuration can copy selected allowlisted files to a remote executor, but it cannot guarantee equal host and executor model catalogs.

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.

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.

Claude ACP also has a narrower built-in rule. When the agent uses the host-injected kandev MCP server, Kandev automatically selects an offered allow-once response, or allow-always when allow-once is not offered, even when Auto-approve all permissions is disabled. This covers every tool on that server, including task creation, task deletion, and plan changes. It is not a saved approval decision and is recreated for each task or Quick Chat session. Kandev still enforces MCP authentication, task and session authorization, user-question barriers, and workflow gates. Shell commands, file operations, third-party tools, and ambiguous requests keep the normal permission flow.

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. When native continuation is unavailable, Kandev uses an explicit recovery action and bounded saved history. It does not restore private harness state or repeat an uncertain prompt. See Automation and MCP.

When native continuation is unavailable, Kandev parks unattended work and shows a recovery action. A provider retry, status update, or dismissed notice does not clear this block. An operator must choose the recovery action before the original work can run again. A context continuation creates a new native conversation from saved history. It does not restore private harness state.

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.

Terminal custom profiles use passthrough and preserve the CLI's native PTY interface. This is useful when the native terminal has features that ACP does not expose, but Kandev cannot manufacture structured capabilities that are absent. Custom ACP profiles use structured ACP sessions. 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.

Choose and prepare local Cursor MCP servers

On a saved Cursor agent profile, enable importing local MCP servers and choose whether to inherit enabled servers or use only your selected servers. Refresh discovery to see available server names grouped by plugin and whether reusable credentials exist. A credential badge means data is available, not that a connection has been verified. Selecting no servers in selected-only mode imports none. Saved selections remain visible if discovery is temporarily unavailable.

The task's workspace preparation shows discovery, selection, credential reuse, server approval and connection verification. Kandev applies the source repository and task workspace disables before approving imported connections. A profile selection cannot override those disables or executor policy. Host imports are limited to eligible local/worktree executions using the backend's home directory.

When verification requires provider consent, choose Authenticate on the preparation step. Kandev opens Cursor's native login flow in the task terminal; complete its browser consent and choose Retry connection. For Cursor ACP, recovery reloads the same task conversation. Automatic reload of a running Cursor terminal session is currently unavailable because Kandev does not own its native chat ID; Kandev never resumes an arbitrary latest chat. Preparation commands do not create agent chat turns, and automatic server approval does not bypass tool-call permissions. The login-terminal action currently requires a POSIX host shell; native Windows login recovery is unavailable.

If native approval or verification fails, expand the preparation details to review the operation, failure stage, optional exit status and sanitized cause. These details do not include raw command output or credential values. If retry reports that the agent is using the session, wait for its current turn to finish before trying again. An early busy check runs no native command. A prompt can also start after retry begins, after approval or verification commands have run. In that case Kandev keeps the existing preparation details and rejects the session reload without stopping, reloading or replaying the active prompt.

Share local Cursor MCP credentials

The Share local Cursor MCP credentials profile option is enabled by default for Cursor ACP and custom terminal profiles that use Cursor's MCP strategy. It applies only to local and worktree executions that use the same home directory as the Kandev backend. Remote and container executors, and profiles that set a different HOME, do not share the backend user's credentials.

On launch, Kandev combines valid mcp-auth.json files from other local Cursor projects into ~/.cursor/kandev-mcp-auth-unified.json. For duplicate server names, an object containing an access or refresh token takes precedence over registration-only data. Within each group, the newest source file wins; equal timestamps use project path order. Kandev selects the entire object, preserving its matching client registration, without combining credentials from different sources.

Kandev links the current project's auth path to this private shared file. It preserves an existing regular mcp-auth.json file. While sharing is enabled, it replaces an existing symlink at that path when it points elsewhere. Disabling sharing does not restore the replaced target. On a disabled launch, Kandev removes only its own project auth link and leaves unrelated symlinks unchanged.

Imported plugin definitions retain Cursor's plugin-<plugin-name>-<server-name> identity so existing workspace credentials match. Credential sharing and server import are separate preferences. Importing servers authorizes Kandev to approve only the eligible imported connections through Cursor's native CLI before starting the agent. This does not grant permission to invoke their tools. Automatic imports honor disabled-server preferences from the task's primary source repository and its own workspace. Other workspaces can supply credentials, but their disabled settings are not inherited.

For marketplace plugins, Kandev reads Cursor's enabled-plugin inventory and uses only the exact cached revision it identifies. This currently supports the observed macOS keychain installation. If the inventory cannot be read, local plugin and global MCP definitions remain eligible. If the selected workspace disable state cannot be read safely, automatic imports are skipped. Explicit profile and user-owned project entries are preserved. Kandev does not sign you in automatically, refresh Cursor account tokens, install plugins, or automatically approve tools. Provider consent starts only when you choose Authenticate.

The shared auth file is keyed by MCP server name. Kandev does not compare server URLs or OAuth issuers between projects. A project with a matching server name can therefore use a copied credential even when its MCP configuration points to a different endpoint. Enable sharing only for trusted local project configurations. If a credential may have reached an unintended endpoint, revoke it through that provider.

To stop sharing, clear the option and launch that profile again. That launch removes only the Kandev-created link for its project. Running processes keep credentials they already loaded. Cursor may refresh credentials through the link, but Kandev does not copy refreshed credentials back to source projects. A later launch rebuilds the shared file from those source projects. Kandev preserves a native-refreshed credential while its original source remains unchanged. Changed or removed source credentials invalidate that preservation; Kandev does not treat an old shared snapshot as an independent source.

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 start: Retry is limited to strict exact-package ETARGET, recognized temporary npm errors, and an ordinary pre-ACP exit with complete generation-matched evidence of empty stderr. Other permanent or unclassified errors and incomplete evidence do not retry. Kandev confirms cleanup and keeps the selected package and npm trees. If startup still fails, review the card's technical details and verify the service user's npm configuration and registry. Use Settings > Agents to prepare another trusted stable version when needed. 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.