Companion Offload

Offload the current Claude Code session to a remote Companion sandbox so it can continue running autonomously in the cloud.

When to use

• The user says "offload this task" or "run this in the cloud"
• A long-running task needs to continue without tying up the local machine
• The user wants to hand off work to their Companion sandbox

Prerequisites

• The companion CLI must be installed and the user must be logged in (companion login)
• An active sandbox must exist and be running (companion ls to check)
• rsync must be available locally

Instructions

Step 1: Verify companion CLI is available and user is logged in

companion whoami

If this fails, tell the user to run companion login first.

Step 2: Check that a sandbox is running

companion ls

If no sandbox exists or it's not running, tell the user to create one with companion create <handle>.

Step 3: Inject SSH key into the sandbox

Use --inject-only to set up SSH access without connecting:

companion ssh --inject-only

This outputs the SSH key path and the manual SSH command. Parse the output to extract:

• The key path (e.g. ~/.companion/ssh/id_ed25519_<handle>)
• The sandbox handle

Step 4: Build the SSH/rsync connection parameters

The Companion SSH gateway uses a ProxyCommand. Construct the connection parameters:

HANDLE="<sandbox-handle-from-step-2>"
KEY_PATH="$HOME/.companion/ssh/id_ed25519_$HANDLE"
SSH_GATEWAY="${COMPANION_SSH_GATEWAY:-ssh.os.companion.ai}"
SSH_PORT="2222"
PROXY_CMD="sh -c '( printf \"COMPANION:${HANDLE}\n\"; cat ) | nc ${SSH_GATEWAY} ${SSH_PORT}'"
SSH_OPTS="-i $KEY_PATH -o StrictHostKeyChecking=accept-new -o LogLevel=ERROR -o ProxyCommand=$PROXY_CMD"

Step 5: Determine the remote workspace path

ssh $SSH_OPTS node@$HANDLE '[ -d /home/node/.openclaw/workspace ] && echo "/home/node/.openclaw/workspace" || ([ -d /home/node/.pi/workspace ] && echo "/home/node/.pi/workspace" || echo "NONE")'

If NONE, use /home/node/.openclaw/workspace and create it:

ssh $SSH_OPTS node@$HANDLE 'mkdir -p /home/node/.openclaw/workspace'

Store the result as REMOTE_WORKSPACE.

Step 6: Install Claude Code on the sandbox if missing

ssh $SSH_OPTS node@$HANDLE 'command -v claude >/dev/null 2>&1 && echo "installed" || echo "missing"'

If missing:

ssh $SSH_OPTS node@$HANDLE 'curl -fsSL https://claude.ai/install.sh | sh 2>/dev/null || npm install -g @anthropic-ai/claude-code'

Step 7: Sync the repository to the sandbox

Use rsync over the SSH ProxyCommand to transfer the current project:

rsync -avz --progress \
  --exclude='node_modules' \
  --exclude='.git/objects' \
  --exclude='__pycache__' \
  --exclude='.venv' \
  --exclude='venv' \
  --exclude='.next' \
  --exclude='dist' \
  --exclude='build' \
  -e "ssh $SSH_OPTS" \
  "$(pwd)/" "node@$HANDLE:$REMOTE_WORKSPACE/"

Step 8: Sync the Claude session and config

Transfer the project-level .claude/ directory (session history, project memory) if it exists:

rsync -avz --progress \
  -e "ssh $SSH_OPTS" \
  "$(pwd)/.claude/" "node@$HANDLE:$REMOTE_WORKSPACE/.claude/"

Also sync the global ~/.claude/ directory (global settings, global memory, credentials, CLAUDE.md):

rsync -avz --progress \
  -e "ssh $SSH_OPTS" \
  "$HOME/.claude/" "node@$HANDLE:/home/node/.claude/"

Both are needed: the project-level .claude/ has session history for --continue, and the global ~/.claude/ has settings, global memory, and the user's global CLAUDE.md instructions.

Step 9: Transfer environment variables

Capture relevant env vars (especially ANTHROPIC_API_KEY) and send them to the sandbox:

env | grep -v '^_=' | grep -v '^SHELL=' | grep -v '^TERM_' | grep -v '^SSH_' | \
  grep -v '^DISPLAY=' | grep -v '^HOME=' | grep -v '^USER=' | grep -v '^LOGNAME=' | \
  grep -v '^PATH=' | grep -v '^PWD=' | grep -v '^OLDPWD=' | grep -v '^SHLVL=' \
  > /tmp/companion_env_export.txt
rsync -avz -e "ssh $SSH_OPTS" /tmp/companion_env_export.txt "node@$HANDLE:$REMOTE_WORKSPACE/.companion_env"
rm -f /tmp/companion_env_export.txt

Step 10: Launch Claude Code on the sandbox

If the user provided a specific task/prompt to offload:

ssh -t $SSH_OPTS node@$HANDLE "cd $REMOTE_WORKSPACE && set -a && source .companion_env 2>/dev/null; set +a && claude --dangerously-skip-permissions --prompt '${TASK_PROMPT}'"

Otherwise, continue the session:

ssh -t $SSH_OPTS node@$HANDLE "cd $REMOTE_WORKSPACE && set -a && source .companion_env 2>/dev/null; set +a && claude --dangerously-skip-permissions --continue"

Step 11: Confirm to the user

After launching, tell the user:

• The session is now running on their Companion sandbox
• They can reconnect with: companion ssh then cd $REMOTE_WORKSPACE && claude --continue
• To sync results back locally: rsync -avz -e "ssh $SSH_OPTS" node@$HANDLE:$REMOTE_WORKSPACE/ ./

Important notes

• Always exclude node_modules, .git/objects, and other large directories from rsync
• The --dangerously-skip-permissions flag is required so the remote session runs autonomously
• If the sandbox already has ANTHROPIC_API_KEY set, the offloaded session will use it. Otherwise ensure Step 9 transfers it.
• Session history in .claude/ gives the remote Claude full context of the local conversation
• The SSH gateway at ssh.os.companion.ai:2222 routes connections via the COMPANION:<handle> prefix

Error handling

• If companion whoami fails: user needs to companion login
• If companion ls shows no sandbox: user needs to companion create <handle>
• If SSH key injection fails: sandbox may not be running
• If rsync fails: check disk space on sandbox
• If Claude is not installable: ensure Node.js >= 18 is on the sandbox