apus attach launches Claude Code with a strict temporary MCP config bound to one Gateway session.

apus attach [target]

target accepts a Control UI session URL, a compact host/agent/ref, a bare short reference, or a literal agent:... session key. A URL or host target authoritatively selects that Gateway; a bare reference uses the configured or default Gateway.

apus attach
apus attach https://gateway.example/dashboard/main/movies-a1166b81
apus attach movies-a1166b81
apus attach --session agent:main:telegram:123 --ttl 600000
apus attach --print-config

Options:

• --session <key> binds the grant to a Gateway session. Defaults to the main session.
• --url <url> selects a Gateway for a bare reference or --session key. Do not combine it with a URL target.
• --token <token> and --password <password> provide explicit Gateway auth.
• --tls-fingerprint <sha256> pins the Gateway TLS certificate.
• --ttl <ms> requests a positive grant TTL in milliseconds. The Gateway applies its own ceiling.
• --bin <path> selects the Claude Code binary. Default: claude.
• --print-config writes the temporary .mcp.json, prints the launch command and env, and leaves the grant live until TTL expiry (it does not spawn Claude Code or revoke the grant).

Pass either a positional target or --session, not both. Short references are resolved before the scoped attach grant is minted; a missing session is never created implicitly.

A URL or host target never reuses configured credentials or APUS_GATEWAY_TOKEN / APUS_GATEWAY_PASSWORD. It uses the stored device token for that exact Gateway origin, or explicit --token/--password credentials. On first contact, pass one of those credentials once, approve the pairing request in that Gateway's Control UI, and retry; see Devices. Session URLs must stay credential-free: userinfo and sensitive query or fragment parameters such as token and password are rejected.

Target resolution uses the same session target error matrix as apus tui.

The bearer token is passed through environment variables, not argv. Apus launches Claude Code with --strict-mcp-config --mcp-config <path> so ambient Claude MCP servers do not join the attached session. Normal launches (without --print-config) revoke the grant when the Claude Code process exits.

If an attached tool asks a structured question, answer it through the question controls in the Control UI or native app. An attach grant scopes tools to a session but does not identify an active Apus run or its original caller permissions, so ordinary channel text cannot claim that question. See Ask user.

See also: Control UI URLs, Devices, Gateway CLI, MCP CLI, and ACP CLI.