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 through a saved Remote Profile.
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", "--remote-url", "https://caplets.example.com/caplets"]

Generic MCP JSON:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach", "--remote-url", "https://caplets.example.com/caplets"]
    }
  }
}

Remote Login

For a self-hosted remote, first create a short-lived Pairing Code on the server:

caplets remote host pair --host-url https://caplets.example.com/caplets

If the server uses a non-default credential state directory, pass the same directory with --state-path that the server uses for caplets serve --remote-state-path.

Then log in once on the client and configure the agent to launch attach:

caplets remote login https://caplets.example.com/caplets
caplets attach --remote-url https://caplets.example.com/caplets

Enter the Pairing Code at the hidden prompt from caplets remote login. Use --code-stdin for automation instead of putting Pairing Codes in shell history.

For Caplets Cloud native integrations, log in once and then set the Cloud URL selector:

caplets remote login https://cloud.caplets.dev
export CAPLETS_MODE=cloud
export CAPLETS_REMOTE_URL=https://cloud.caplets.dev

opencode

Saved Remote Profiles are used by caplets attach and native integrations. Agent configs should not contain Caplets remote tokens or passwords.

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