# Runtimes

Runtimes are the AI coding-agent implementations that agentteam can run for agents.
`builtin` is the AgentTeam-managed OpenCode runtime shipped with AgentTeam Desktop.
OpenCode, Claude Code, Codex, and Kimi Code binaries remain available as advanced
detect/use/configure paths. Agents reference runtime names; the daemon turns
that profile into a concrete runtime session and injects the local MCP bridge
information needed for channel collaboration.

## Supported Types

Runtime detection is ordered by priority:

| Runtime type | Default binary | Notes |
|--------------|----------------|-------|
| `builtin` | AgentTeam-managed `opencode` | Shipped with AgentTeam Desktop; starts with default args `serve`; exposes `/global/health` |
| `opencode` | `opencode` | OpenCode path from PATH or manual binary configuration |
| `claude` | `claude` | Claude Code interactive runtime |
| `codex` | `codex` | Codex app-server integration path; agentteam starts `codex app-server` |
| `kimi` | `kimi` | Kimi Code Agent Client Protocol integration path; agentteam starts `kimi acp` |
| `pi` | `pi` | Pi RPC integration path; agentteam starts `pi --mode rpc` |

`claude-code` is accepted as a legacy alias for `claude` by runtime type
validation. `builtin` uses the OpenCode driver, but it resolves the binary from
the AgentTeam Desktop artifact instead of the user's OpenCode install.

## Detection

For Builtin Runtime, the resolver uses the managed binary bundled in the AgentTeam
Desktop release artifact. Missing, non-executable, or version-mismatched
managed OpenCode means the AgentTeam Desktop installation is incomplete.

For external runtimes, the daemon can scan `PATH` and common package-manager
install locations for default binaries. Those fallback locations include npm
prefix directories, user bin directories, Homebrew paths, Windows package-manager
shim directories such as Scoop, Chocolatey, and WinGet links, and common Node
manager paths such as nvm, fnm, Volta, asdf, and mise. OpenCode uses
the `opencode` runtime type and can also be selected through a manual binary
path. Kimi Code uses the `kimi` runtime type and must expose the public
`kimi acp` entrypoint. AgentTeam injects the agent's configured model provider when
starting Kimi and does not invoke Kimi's interactive login flow.
On Windows, explicit runtime detection also reads user and machine `PATH`
values from the environment registry so newly added runtime directories can be
found without restarting AgentTeam Desktop.
Detection records:

- Runtime type
- Binary name
- Resolved path
- Whether the binary is installed
- Whether the binary is a launch candidate for AgentTeam
- Version, when the runtime supports `--version`
- A reason code and message when setup is incomplete

Detection runs on startup and the dashboard Runtime manager can re-detect on demand. The daemon does not continuously rebuild the execution registry from runtime subprocess probes, so transient probe failures do not evict an otherwise usable agent runtime.

The dashboard separates runtime detection states instead of treating every
non-ready runtime as missing. LLM models and credentials belong to agent
configuration or dedicated runtime configuration APIs; they do not affect the
runtime ready state here:

| Status | Meaning |
|--------|---------|
| `missing` | No usable binary was found, or Builtin Runtime is missing |
| `unsupported` | A binary was found, but it lacks a required capability or has an unsupported version |
| `ready` | The runtime is installed and capable |

## Managed And External Runtime Policy

AgentTeam Desktop does not provide one-click installation or upgrade for
OpenCode, Claude Code, Codex, or Kimi Code runtimes. The dashboard and CLI runtime surfaces
only detect, validate capability, show status, and expose remediation guidance.

The following runtime installer surfaces are intentionally absent:

- Dashboard install/upgrade buttons for runtimes
- Runtime SSE installer endpoints
- Runtime install-command endpoints
- `agentteam onboard --runtime` installer selection
- `agentteam doctor --fix-runtime` auto-install behavior
- Launch-time or app-build-time OpenCode auto-install

Builtin Runtime upgrades with AgentTeam Desktop. Release artifacts must include the
platform-specific OpenCode executable at a managed runtime path such as
`Contents/Resources/runtimes/opencode/opencode` in a macOS app bundle or
`runtimes/opencode/opencode` next to the desktop executable in non-bundle
layouts, plus `models.json` in the same `runtimes/opencode/` directory. Local
`make build` stages the same managed runtime path next to
`bin/agentteam` for developer testing; this does not install or upgrade an external
OpenCode runtime. Release builds can declare the expected OpenCode version; a
mismatch is reported as an incomplete AgentTeam Desktop installation.

`agentteam onboard --runtime` prints detection status. `agentteam doctor --fix-runtime`
prints remediation guidance. Neither command installs external runtimes.

## Runtime Configuration

Normalized runtime records contain:

| Field | Meaning |
|-------|---------|
| `name` | Runtime name used by agents |
| `type` | One of the supported runtime types |
| `enabled` | Whether the runtime can be used |
| `binary` | Binary name or path |
| `args` | Additional process arguments |
| `port` | Runtime port when a runtime needs one |
| `health.path` | Health endpoint path |
| `health.interval` | Health check interval |
| `health.timeout` | Health check timeout |
| `env` | Extra environment variables |

Default runtime records are derived from detection and type defaults. Persisted
profile records may still carry manual binary paths, args, health settings, and
environment overrides for advanced external-runtime use.

For external runtimes, AgentTeam Desktop captures exported variables from the user's
shell startup environment and adds them to spawned runtime processes when the
daemon process did not already have the same variable. This lets runtimes use
provider-specific settings such as custom LLM credentials, regions, API
versions, and profiles configured in shells including fish, zsh, or bash. The
captured shell environment is used for runtime launch and runtime `env_key`
resolution; it is not written back into the daemon process environment. `PATH`
is handled separately by the runtime detection and launch path logic.

Permissions, skills, and MCP settings are assembled from the AgentTeam agent start
configuration and passed to the runtime process at session start.

## MCP Loopback Proxy Handling

When a runtime reaches agentteam's local MCP bridge on `127.0.0.1`, `localhost`, or `::1`, a system HTTP proxy can break local traffic. `AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY` controls loopback `NO_PROXY` injection:

| Value | Behavior |
|-------|----------|
| `auto` | Default; append loopback hosts only when the MCP endpoint is local |
| `on` | Always append loopback hosts |
| `off` | Never modify `NO_PROXY` / `no_proxy` |