/teleport

name: teleport
description: Move the current task to a new HumanLayer session on another host (sandbox, cloud VM, or a machine you can SSH into).

Move this task to a new session on another host. Ask every question up front, then do the work without more check-ins. Keep messages short.

The remote session is a new session in the same task. It does not resume this conversation. It starts from `handoff.md` and the pushed branch.

1. Gather context, then ask once

Before asking anything, collect:

• Stage: use `prod` unless `HUMANLAYER_SESSION_URL` or the user points elsewhere. `app.humanlayer.com` = prod, `app.codelayer.cloud` = beta, `app.dev.codelayer.gg` = dev.
• Session, task, task slug, workspace, and host IDs, plus the coding agent, provider, model, effort, and permission mode: read them from the `<humanlayer_session>` block in your system prompt.
• Task directory: `.humanlayer/tasks/<task-slug>/`.
• Git: branch, `git status`, and the remote to push to (for example `origin` or `upstream`). If there is only one remote, use it.
• Saved defaults: `.humanlayer/teleport.json`, if present.
• Project workspace, if the workspace ID is set. The new host builds its worktree from the workspace's branch on the project's remote, so read both:

  humanlayer api project-workspaces get-status --task-id <task-id> > /tmp/hl-workspace.json
  jq -r '.workspace.projectId, (.workspace.repositories[] | [.repositoryIdentity, .remoteUrl, .branch, .default] | @tsv)' /tmp/hl-workspace.json

Push to the git remote whose URL matches the project's `remoteUrl`, not a fork. If more than one remote matches, ask.

• Secret files: `.env` files, local settings, and keys that git does not carry. Find them and list their key names with [references/secrets.md](references/secrets.md). Never print a value.

Then ask one message covering only what is still unknown:

1. Compute:

• Sandbox: Freestyle, Daytona, E2B, Modal, or any other service that can run Linux
• Cloud VM: EC2, GCP, or another provider; new or existing
• Existing machine over SSH or Tailscale (for example a Mac mini)

2. How to reach the host (SSH alias, user, provider account or project). 3. Which agents to install and sign in: Claude Code, Codex, or both. Default to the agent running this session. 4. Stage, if it is not clear. 5. Which remote to push to, if there is more than one. List them and mark the branch's tracking remote, if any. 6. Which secret files to copy. List each file with its key count and your advice (copy, skip, or ask), and flag keys that look tied to this machine or to production. Name keys; never show values.

If the worktree is dirty, say in the same message: "Uncommitted changes will be committed and pushed to `<branch>` before the move." Do not ask a separate question about it.

If the user gives reusable answers that are not in `teleport.json`, offer to save them in that same message.

2. Saved defaults

`.humanlayer/teleport.json` holds project defaults. The user's words in this session win over the file. Never save secrets, tokens, one-time codes, or session IDs. `secretFiles` holds paths only.

{
  "stage": "prod",
  "compute": "freestyle",
  "host": "my-dev-vm",
  "access": "freestyle-ssh",
  "agents": ["claude"],
  "daemonSupervisor": "systemd",
  "secretFiles": [".env", "packages/db/.env"],
  "notes": ["Persistent VM. Do not stop it after the move."]
}

3. Save the work

1. Commit all changes and push the branch. Stop if a file looks like a secret (`.env`, keys, credentials) or no writable remote exists, and tell the user the exact blocker.

• For a project workspace, push to the project's remote. If the current branch is not the workspace branch, push both, and name the current branch in the session prompt. The new host starts from the workspace branch as pushed; unpushed commits stay behind.

2. Write `.humanlayer/tasks/<task-slug>/handoff.md` with everything the next agent needs:

• goal and current status
• decisions made and why
• work done, work left, and the next step
• open questions and known problems
• key files and artifacts to read
• repo, branch, remote, and commit SHA
• source session URL

4. Prepare the host

Use the provider CLIs already signed in on this machine. Check `--help` when unsure. Do not stop or delete compute when done.

Run every interactive step in a named tmux session on the host (`hl-auth`, `hl-claude`, `hl-codex`, `hl-gh`, `hl-daemon`). Read the pane with `tmux capture-pane -p`, show the user any URL or code, and send their answers with `tmux send-keys`.

1. Install missing tools: `tmux`, `git`, Node or Bun, `@humanlayer/cli`, and the chosen agents. 2. Update the HumanLayer CLI, Claude Code, and `gh` to the latest version, even if they are already installed. Base images often ship old copies.

   bun add -g @humanlayer/cli@latest                # or npm install -g @humanlayer/cli@latest
   curl -fsSL https://claude.ai/install.sh | bash   # installs to ~/.local/bin and keeps itself updated
   sudo apt-get update && sudo apt-get install -y --only-upgrade gh   # or brew upgrade gh

Put `~/.local/bin` and the HumanLayer CLI's directory first on `PATH`, then check that `command -v humanlayer claude gh` finds the new copies. 3. HumanLayer login: `humanlayer login` (with `--dev` or `--beta` if needed). If the account has more than one organization, the CLI lists them; ask the user which to use and send the choice. 4. Agent login:

• Claude Code: `claude`, then finish the login. Test with `claude -p hi`.
• Codex: `humanlayer agents auth codex login` (stage flag before `agents`), and pick device code. Do not use `codex login`: HumanLayer keeps its own Codex credentials, so the Codex CLI login does not reach HumanLayer sessions. Check with `humanlayer agents auth codex status`, then test with a short `humanlayer codelayer` prompt.

5. GitHub: `gh auth status`; if signed out, run `gh auth login` and finis