Remote Attach

Use caplets attach when the agent should connect to a remote or Cloud-backed Caplets runtime instead of starting local backends.

Modes

Caplets native integrations use the same mode names as caplets attach:

Mode	Use it when
local	The agent should start Caplets against local user and project config.
remote	The agent should connect to a self-hosted Caplets service.
cloud	The agent should connect to Caplets Cloud with explicit CAPLETS_REMOTE_* or CAPLETS_CLOUD_* environment values.
auto	Caplets should use Cloud for Cloud URLs, self-hosted remote for non-Cloud URLs, and local mode when no remote URL is set.

MCP client config

Codex:

[mcp_servers.caplets]
command = "caplets"
args = ["attach"]

Generic MCP JSON:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach"]
    }
  }
}

Environment

For a self-hosted remote:

export CAPLETS_MODE=remote
export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
export CAPLETS_REMOTE_TOKEN=...

caplets attach

Use CAPLETS_REMOTE_USER and CAPLETS_REMOTE_PASSWORD instead of CAPLETS_REMOTE_TOKEN when the remote uses Basic Auth.

For Caplets Cloud native integrations, set the Cloud URL plus a workspace and token:

export CAPLETS_MODE=cloud
export CAPLETS_REMOTE_URL=https://cloud.caplets.dev
export CAPLETS_REMOTE_WORKSPACE=...
export CAPLETS_REMOTE_TOKEN=...

opencode

Saved Cloud auth from caplets cloud auth login is used by the caplets attach CLI path. Native integrations do not read the saved auth store directly.

Run a finite Project Binding smoke path before wiring an agent:

caplets attach --once

caplets attach --once validates the configured Project Binding WebSocket URL once and exits. Use it when a remote project binding is expected, not as a generic attach manifest check.

Project binding

caplets attach can keep a local project bound to a remote runtime. Use this when the remote capability needs project-local context while the agent still talks to one Caplets MCP server.

Attach connects to the runtime attach API at /v1/attach. Ordinary MCP clients that are not using attach continue to connect to /v1/mcp, which still honors the configured exposure mode for each Caplet.

Check remote health and binding diagnostics with:

caplets doctor