Remote Attach

Use caplets attach when the agent should connect to a remote or Cloud-backed Caplets runtime instead of starting local backends. caplets attach <url> is a stdio MCP adapter; it does not run an HTTP server.

Use caplets serve --transport http --upstream-url <url> for a long-running stacked runtime that composes local user/global Caplets, per-session project Caplets, and an upstream Caplets host.

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", "https://caplets.example.com/caplets"]

Generic MCP JSON:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach", "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 https://caplets.example.com/caplets

For a stacked local runtime, run the HTTP service outside the agent process:

caplets serve --transport http --upstream-url https://caplets.example.com/caplets

Then configure the agent with caplets attach <local-runtime-url>. The attach adapter sends its current working directory as the session project root, so project Caplets are resolved per attached client instead of from the long-running server’s startup directory.

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.

Stacked runtimes also attempt upstream Project Binding automatically when an attach or native session supplies a project root and the upstream supports Project Binding. If the upstream binding path is unavailable, local project Caplets and non-project upstream Caplets remain available with a diagnostic.

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