Optional provider packages

External integrations live in independent @devctl/provider-* packages. The core owns authorization, encrypted secrets, durable resource/session history, budgets, reconciliation and the user interface. A package owns its external API/SDK, endpoint mapping, credentials metadata and capability-specific behavior.

Install the provider, configure its credentials, then grant access to the Projects or sessions that need it. These are separate operations. Removing an adapter preserves session and resource history, but does not delete its remote resources or transfer access to another user. TUI and web read the installed capability catalog from the same controller. See feature limits and ownership.

There is no universal VM interface. Package discovery shares a small versioned manifest and loader; each capability has its own contract:

Kind Contract / consumer Bundled packages
cloud-vm cloud-provider-kit / cloud provisioner provider-hetzner, provider-digitalocean, provider-vultr, provider-linode, provider-hostman, provider-proton, provider-fly (prepared host preview)
compute contracts/compute / controller provider-boat, provider-prized, provider-agent37, provider-superserve, provider-freestyle, provider-celesto, provider-createos, provider-digitalocean-harness, provider-e2b, provider-instabox, provider-modal, provider-sandboxer, provider-daytona, provider-cloudflare-sandbox
git git-provider-kit / controller provider-github, provider-gitlab, provider-git-generic
decisions decisions-provider-kit / controller provider-jev, provider-cloudflare-decisions, provider-openai-decisions, provider-subq-decisions, provider-perplexity-decisions, provider-laya-studio, provider-layahost, provider-laya-decisions, provider-kev-decisions, provider-von-decisions, provider-systemone-compatible
publicTunnel launch + URL parser / web gateway provider-cloudflare-tunnel, provider-localhost-run, provider-ngrok
managedService CLI and optional service definition / operator tools provider-s3, provider-dokploy
messenger messenger-provider-kit / scoped sessions, terminal input and permission decisions / controller provider-telegram, provider-slack, provider-teams
mcpTunnel private callback / existing server operator API / controller provider-openai-mcp-tunnel
agent-cli agent-cli-kit / existing container/session runtime and shared controller/TUI/web catalog 25 provider-agent-* packages; capability matrix

Boat is a disposable sandbox capability, separate from cloud VM provisioning. Claude/Codex launch, detach/attach and durable history remain the existing session mechanism. See Boat workspaces for the snapshot/persistence limitations. A packaged provider can still be unavailable or require preview access. Catalog loading does not check paid entitlement or send project data. See the current Decisions provider contracts and availability (source access required).

Install, disable, remove

Bundled packages are workspace packages in this checkout; they need not be published to an external registry. Third-party packages can be installed from a registry or a local packaged archive with pnpm. Provider modules execute trusted operator code; Project sessions and browser payloads cannot choose arbitrary module paths.

Install compute/Git/Decisions/messenger packages in the controller's optional dependencies:

pnpm --filter @devctl/controller add --save-optional /path/to/provider-package.tgz

Install cloud VM, tunnel and operator service packages in the root's optional dependencies:

pnpm add -w --save-optional /path/to/provider-package.tgz

After installation, rebuild the affected control-plane image for controller/TUI/VM providers and restart the affected control-plane service; web-only tunnel changes need a gateway restart. Existing Project containers and agent sessions do not need a toolchain upgrade. Do not rebuild or restart all running Projects for a provider catalog change.

To remove a package, use the matching pnpm --filter @devctl/controller remove <package> or pnpm remove -w <package>, then rebuild/restart the affected consumer. Removing code does not destroy paid resources, delete accounts, erase history or revoke upstream tokens. Clean up resources while the provider is still installed; otherwise reinstall the package or use the provider console. Never infer resource deletion from an unavailable package.

These operator environment variables override automatic discovery with a comma-separated package list; an empty value disables that family:

Set the variable on the process/container that owns that family. The cloud CLI forwards its cloud-provider selection into its tools container. These lists contain package names only; credentials use existing secret stores or hidden token prompts.

Package contract

Export manifest and createProvider from the package entrypoint. Export ./package.json and repeat the manifest's identity in package.json.devctlProvider so discovery can select the right family before executing package code:

{
  "name": "@example/provider-example",
  "type": "module",
  "exports": { ".": "./index.mjs", "./package.json": "./package.json" },
  "devctlProvider": {
    "apiVersion": 1,
    "kind": "cloud-vm",
    "id": "example",
    "displayName": "Example Cloud"
  }
}

The factory implements the selected family's contract. Unsupported API versions, wrong capabilities, duplicate identities, missing modules and failed imports are isolated. Diagnostics omit exception bodies that might contain credentials. User-visible provider lists come from installed manifests; the cloud picker also reads bundled icon data from the manifest, without third-party image requests.

Native agent packages export a versioned agent-cli manifest and adapter factory. Install a third-party agent package in both @devctl/runtime and @devctl/controller optional dependencies, then rebuild/restart those control-plane consumers. Provider identifiers accept bounded safe plugin IDs; no core allowlist, UI switch or schema edit is needed for a future package. Compatible hook profiles are independent of the provider ID; a package can ship standalone integration assets for another native protocol. Typed kit declarations define launch, version, environment, normalization, integration and health behavior.

Package installation and native CLI installation are separate. Native binaries remain inside the existing Project container and are never implicitly installed or authenticated on launch. devctl agent clients lists the catalog; devctl account client ACCOUNT WORKSPACE health|install-cli|install-integration|remove-integration performs explicit account-scoped actions. Native npm installation uses the existing managed cache/immutable version mechanism; binary/manual/uv clients require their documented container installer. Existing Project Internet grants remain enforced, including separately granting the configured model, login and startup endpoints. Adding an adapter never widens runtime egress.

Removing an agent package retains its live tmux/PTY pane, account configuration and history. Reattach remains available; a new launch or native resume requires the installed adapter and an exact native session identity. No missing package falls back to another client or a new conversation. Native agent clients documents capability gaps, owned integration removal and current verification.

Cloud VM factories implement listRegions/create/get/destroy and declare defaults and a token environment variable. Compute factories declare explicit capabilities and support durable external-resource reconciliation. Do not pretend a sandbox is a persistent VPS to fit the cloud-VM contract.

Proton Computer implements managed persistent hosts through its official CLI's API, including asynchronous operation polling and a hostname/port SSH gateway. Its token uses the existing hidden prompt/stdin path; creation recovery stores an idempotency key and operation ID, never the token. Fly Machines uses the same managed-host path with an explicit prepared Docker image, dedicated app, existing persistent volume and public SSH endpoint. Its API integration manages only the Machine; app/IP/volume retention and the unverified live deployment boundary remain explicit in the picker and docs.

Managed service assets and compatibility

The host service catalog already consumes generic YAML/JSON definitions from host-services.d; installing a package does not silently grant Projects access or start a network service. Existing service grants and lifecycle protocols remain unchanged. A package may ship a definition and gateway assets for explicit setup.

An operator can also register a custom gateway directly, without a provider package or changes to devctrl's source. Custom gateways documents the local, SSH and standalone services.d paths, a TypeScript example, project grants and optional lifecycle scripts. Discovery loads YAML/JSON definitions; it does not automatically run TypeScript files.

./devctl provider list lists installed operator service packages. ./devctl provider <id> <arguments> runs their declared CLI. The old ./devctl s3-gateway command remains a compatibility alias. Old gateway script paths are thin compatibility exports; implementation lives in the corresponding package. For a standalone Dokploy installation, copy packages/provider-dokploy/gateway.mjs and its service.yaml, rather than the compatibility wrapper in examples.

Tunnels keep generic health probes, retries and fallback in the web gateway. Package metadata controls automatic order and first-attempt timeout. credentialRequired and autoEligible: false keep credential adapters out of automatic fallback. Optional availability() reports runtime prerequisites; launch() may return a child env, redactions, and privateOutput: true to keep credentials and raw provider errors out of arguments/status/logs. Ngrok uses the server controller’s encrypted integration credential storage and requires a separately installed v3 executable. Saved public URL settings and prerequisite details. No installed tunnel package leaves a working local web console. Explicitly choosing a missing provider reports an unavailable-package error rather than switching silently.

Telegram, Slack and Microsoft Teams are optional messenger packages with encrypted controller credentials and authenticated private-chat pairing. They share the same scoped session/approval engine in messenger-provider-kit; transport code and upstream authentication stay in each package. The Integrations section groups Decisions and Remote interface connections. See Integrations, Telegram, Slack (source access required) and Teams (source access required).

Private external MCP transports use the mcpTunnel capability and optional controller packages. Their factory receives a narrowly held private MCP callback, selected tool schemas, encrypted-at-rest credential material and a live authorization predicate. It owns start, stop, safe status and the provider's process supervision. Only the recovery operator can configure the first shipped transport; ordinary Project grants cannot start it. The OpenAI package pins and verifies its official runtime, uses outbound HTTPS, and tears down its process group/private keys when the controller lease ends. No external SDK is in core. Private MCP setup and current boundaries.

Connection transport and execution boundary

SSH and an HTTPS/WSS console link are connection choices. Explicit local Docker pairing adds an execution host; it does not move the controller onto the laptop. Personal sign-in and device ownership apply on multi-user servers. Continuous folder synchronization through WSS remains a preview with an unresolved clean restart/conflict regression on the observed macOS/VirtioFS stack. See HTTPS client connections for that separate limit.

The installed compute registry currently contains fourteen sandbox adapters. The homepage and the disposable-compute feature page list every bundled adapter with local provider artwork. The feature page links to this catalog instead of presenting Boat as the complete provider selection. The interactive Sandboxes sample uses the same provider identities and marks all accounts as unconfigured; opening the demo never provisions a paid resource.

Adapter boundary Installed packages Current verification limit
Docker-capable sandbox adapter Boat, Agent37, Superserve, Freestyle, Celesto, InstaBox, Sandboxer Adapter fixtures and local Linux command receipts do not prove paid-provider bootstrap or detached-process survival. Provider and image prerequisites still apply.
API execution only Prized, CreateOS, DigitalOcean Harness Runtime, E2B, Modal Sandboxes, Daytona, Cloudflare Sandboxes These adapters declare docker: false; the current managed-session launcher rejects them before paid resource creation.

For exact API mappings, lifecycle limits and upstream sources, read the provider groups: Boat, Prized, Agent37, Superserve and Freestyle, Celesto, CreateOS, DigitalOcean Harness Runtime, InstaBox and Sandboxer, and E2B, Modal, Daytona and Cloudflare Sandboxes. An installed package is implemented adapter code, not proof of a successful cloud deployment. No paid-provider end-to-end verification is claimed by this catalog. Native snapshots, backups, automatic pause and retention remain provider-specific; a Docker-capable declaration does not enable all of them.

DigitalOcean Droplets and DigitalOcean Harness Runtime are separate integrations. Proton Computer and Fly Machines use the cloud-VM contract; Fly requires an explicitly prepared Docker host. Netcup and ServaRica can be connected as existing SSH machines after independent provisioning; no automatic create/delete adapter is registered. See the API assessment (source access required). Package discovery, configuration, API authorization and actual cloud provisioning are distinct states.