Remote Attach

Use caplets attach when an agent should be a thin stdio client for a Current Host. Daemon-first local setup points clients at the local daemon with caplets attach <local-daemon-origin>; generic remote setup uses the same command shape with a Current Host Origin. caplets attach <origin> does not run an HTTP server.

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

Modes

Caplets native integrations use these shared runtime selection modes:

Mode	Use it when
local	The native integration should start local Caplets in-process against user and project config.
daemon	The native integration should use the local daemon through a credential-free loopback Current Host Origin.
remote	The agent should connect through a saved generic Remote Profile selected by a Current Host Origin.
auto	Use a configured generic remote, otherwise a setup-written daemon when present, then local.

CLI Attach or SDK Project Binding

Use CLI Attach when an MCP client needs a stdio Adapter and Caplets should manage the surrounding generic Remote Profile workflow. The CLI uses saved Remote Login credentials to connect the agent to the selected Current Host. Keep credentials out of the agent’s MCP configuration.

Use @caplets/sdk/project-binding instead when an application needs to embed a Project Binding session and already owns all surrounding policy. The SDK caller must provide:

• an isolated createClient instance whose baseUrl is the Current Host Origin, with optional caller-owned static or async auth;
• the exact ws: or wss: /api/v1/attach/project-bindings/connect URL; and
• the project root and caller-supplied fingerprint, or the Node-only filesystem fingerprint helper.

The SDK does not read or write CLI Remote Profiles. It does not discover endpoints, persist credentials, start or poll Remote Login, or turn the Project Binding session into an MCP stdio Adapter. Use caplets remote login and caplets attach when Caplets should own those managed behaviors. Use the SDK only when the embedding application owns them and can keep credentials out of URLs, events, errors, and logs.

In both paths, Caplets core remains authoritative for binding leases, readiness, and synchronization policy; the client keeps the protocol session alive but does not choose those policies. See Project Binding for the SDK endpoint, event, result, and lifecycle contracts.

MCP client config

Local daemon-backed Codex config after setup:

[mcp_servers.caplets]
command = "caplets"
args = ["attach", "http://127.0.0.1:5387/"]

Remote Codex config after Remote Login:

[mcp_servers.caplets]
command = "caplets"
args = ["attach", "https://caplets.example.com"]

Generic MCP JSON:

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

Remote Login

Start generic Current Host Remote Login from the client:

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

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

Host approval commands use the Authoritative Host State backend from the host’s user config. The deprecated --state-path option no longer selects credential state. 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

Remote Attach is the Access Client path. If you need host administration instead of agent runtime access, open the browser dashboard on the same host and complete an Operator approval there. The same approval lane can issue either Access or Operator authority, but only Operator sessions can use the dashboard’s Vault, client-administration, and runtime-control surfaces. See Dashboard.

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

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

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.

Current Host inputs are origins: scheme, host, and optional port only. A trailing root slash is normalized away; non-root paths, queries, fragments, and embedded credentials are rejected before network I/O. Saved generic 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 https://caplets.example.com --once

This validates the selected remote’s 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 /api/v1/attach/*. Ordinary Streamable HTTP MCP clients that bypass Attach use exact /mcp, which continues to honor the configured exposure mode for each Caplet.

Check remote health and binding diagnostics with:

caplets doctor