boxkite

Capability

Session handoff

Move an in-progress local Claude Code, Codex CLI, or opencode session into a fresh boxkite sandbox — full conversation history, not a task summary — and keep interacting with it from there. The CLI keeps running under your own portable, scoped credential, never a copy of your laptop's raw login session.

How a handoff runs

Every step below composes existing, already-reviewed primitives — sandbox creation, file_create, and the same takeover PTY the dashboard's own terminal uses. No new control-plane or sidecar surface was added for this.

How a handoff runs

Locate session

The adapter finds your tool's real on-disk session state (or, for opencode, its own export format) and a portable, scoped credential -- never your raw browser login session.

Install & run

boxkite-handoff is a separate companion CLI, built on the Python SDK — it is not yet published to a registry. Install it from a checkout of this repo:

terminal
pip install ./handoff-cli
BOXKITE_API_KEY=... BOXKITE_BASE_URL=... boxkite-handoff claude-code

Pass --session <id> for a specific session, or omit it to hand off whichever local session was modified most recently.

How credentials stay safe

Your credential is never typed anywhere as a literal value. It's written once to a short-lived file, read back with a single reference to its path, and deleted immediately by that same command — so at no point does the raw token appear in a command, a log line, or shell history.

  • Always the tool's own portable, scoped, independently-revocable token — never your raw browser/OAuth session.
  • Written only to a short-lived file under /tmp, never anywhere that syncs to durable storage.
  • Deleted by the same command that reads it, and every session identifier is validated before it can reach a shell command.

Full technical design

See docs/handoff-adapters.md in the repo for the complete adapter contract, architecture diagrams, and security design behind this.

Supported tools

ToolStatusCredential
Claude CodeSupported — cwd-sensitive resumeclaude setup-token
Codex CLISupported — path-based resumeOPENAI_API_KEY or a personal access token
opencodeSupported — via export/importprovider API key from auth.json
CursorNot yet — cursor-agent's local session store couldn't be confirmed as a portable, copyable file. Raises a clear error rather than faking support.—

The adapter contract is designed for community contribution — adding a new tool means implementing onelocate_session() call, not touching the shared orchestration. See docs/handoff-adapters.md's "Adding a new adapter" section.

Where this fits today

Not an MCP capability, and not a control-plane API

A handoff adapter reads local, on-disk CLI session state on your own machine — that's a fundamentally local operation an MCP tool call (which runs wherever the MCP client invokes it) can't perform on your behalf. boxkite-handoff is a standalone local CLI for exactly this reason, and it composes existing control-plane/SDK primitives rather than adding new ones — there is nothing new to call directly from the Python/JS/Go/Rust SDKs either.

Related

  • Python SDK — boxkite-handoff is built directly on BoxkiteClient.
  • Audit log & takeover — the same channel this feature attaches to, and why everything typed on it gets logged.
  • Secrets management — a different trust boundary (brokering a third-party key to a semi-trusted agent) than a handoff's own credential handling.
  • MCP server — why this capability isn't exposed as an MCP tool.
  • Security model — the broader defense-in-depth posture this feature was built to fit inside, not around.