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"]
    }
  }
}

For a self-hosted remote, start Remote Login from the client:

caplets remote login https://caplets.example.com/caplets

The command prints a short operator code and waits. On the host, a server-local operator reviews the pending login metadata and approves the code from the same server environment that owns the remote credential state:

caplets remote host logins
caplets remote host approve <code> --yes

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. The visible approval code is not an attach credential, but do not put Caplets access or refresh credentials in shell history, agent configs, or environment variables.

After approval, configure the agent to launch attach:

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

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