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:
DEVCTL_CLOUD_PROVIDER_PACKAGESDEVCTL_COMPUTE_PROVIDER_PACKAGESDEVCTL_GIT_PROVIDER_PACKAGESDEVCTL_DECISIONS_PROVIDER_PACKAGESDEVCTL_MESSENGER_PROVIDER_PACKAGESDEVCTL_MCP_TUNNEL_PROVIDER_PACKAGESDEVCTL_TUNNEL_PROVIDER_PACKAGESDEVCTL_SERVICE_PROVIDER_PACKAGESDEVCTL_AGENT_PROVIDER_PACKAGES
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.