Remote Sessions

Remote Sessions move an in-progress Kimchi Coding session from your local machine to a cloud sandbox, so the agent keeps running when you close your laptop, switch machines, or hand off to a teammate. Start the hand-off with /teleport in the CLI, then resume the session from the CLI, the Kimchi console, or VS Code.

Use Remote Sessions when a task is too long to babysit, when you need to switch devices, or when you'd rather not be tied to one terminal.

Prerequisites

• Kimchi CLI v0.1.52 or newer — /teleport and /remote-sessions ship in CLI builds from v0.1.52 onward. Check your version with kimchi --version, and update with kimchi update if needed.

Before you start

• A Kimchi Coding session in progress — start one in your local kimchi CLI or inside a Ferment plan. The session can be in any phase (planning, building, reviewing).
• A task you expect to take a while — /teleport is most useful for jobs where you'll close your laptop, switch contexts, or come back later.

Workspaces and sessions

A workspace is the cloud sandbox your work runs in; a session is one agent run inside it. A single workspace can host multiple sessions at the same time — tab between them with Ctrl+B c / n / p, or browse them all under one workspace via /remote-sessions.

Group related sessions in the same workspace whenever they share a project or repo: different angles on the same task, parallel investigations, or handoffs between agents. Sharing a workspace means shared files, shared state, and a single place to resume from later. Spinning up a new workspace for every session burns through the per-user quota and scatters related work across sandboxes.

Hand off your session to the cloud

/teleport flags

Beyond the default /teleport, a few flags cover common cases:

Examples:

/teleport --workspace mybox task-2                       # new session in an existing workspace
/teleport --git-repo https://github.com/org/repo.git --branch main
/teleport --allow-dirty                                  # ship uncommitted changes

You can also pass an optional positional name to label the session: /teleport my-feature. Allowed characters are letters, digits, -, _. Names must be unique within a workspace.

Git credentials

When /teleport detects a git remote (e.g. github.com), it prompts for a personal access token. The token is forwarded to the sandbox so the remote agent can push and pull from private repositories.

The prompt offers:

• Token input — paste a personal access token. The display is masked.
• Save for future sessions — toggle with Tab. When enabled, the token is saved locally so you won't be prompted again for the same host.
• Skip — press Esc to continue without git credentials. The remote won't be able to access private repos.

If you previously saved a token for the host, kimchi uses it automatically. Use --no-git-token to suppress the prompt entirely.

Work inside the PTY overlay

The PTY overlay behaves like a fullscreen terminal multiplexer on the remote sandbox. Your session, skills, and agent state are already there — keep typing, run commands, and let the agent finish the task.

Tab between sessions

Open and switch between independent sessions inside the same workspace:

Each tab is an independent session inside the same workspace — useful for running a second parallel task or just poking around while the first agent is mid-run. Sessions are long-lived: they keep running on the server after you disconnect, so you can come back later and resume exactly where you left off.

Tabs are lazy by default — their WebSocket only opens when you switch to them, keeping socket usage low. The first tab you open through /teleport is eager (always connected). The chord state resets after one operand; unknown operands are silently consumed so they don't leak into the active shell.

Tab indicators

Push local changes without restarting

If you've made local changes since the initial sync, push them without restarting the session:

/sync up --workspace mybox --source ./src/ --target ~/project/src/

/sync runs rsync between your local machine and the sandbox in either direction — up (local → remote) or down (remote → local). Both directions require --workspace, --source, and --target. Common flags:

Default excludes for directory transfers: node_modules/, dist/, .next/, target/, __pycache__/, .venv/, .env*, *.log, .DS_Store, .kimchi/, plus your repo's gitignored entries (unless --include-ignored is set). Single-file transfers skip these and use only the explicit --exclude patterns.

Pull a directory back to your laptop with a trailing slash on the remote source:

/sync down --workspace mybox --source ~/project/dist/ --target ./dist/

Open the workspace in VSCode

Run /ssh-config inside the overlay, then switch to VS Code → Remote Sessions — the workspace shows up automatically and you can connect straight to the remote filesystem. Everything is wired up; no manual ~/.ssh/config edits required. You get a full editor pointed at the workspace — available immediately, while the agent keeps working in the overlay.

Exit the overlay any time

Press Ctrl+D to drop back to your local kimchi prompt. The sandbox keeps running, the session keeps running, the agent keeps going. Nothing dies.

When a session terminates normally (e.g. you type exit in the shell), its tab closes. If that was the last tab, the overlay exits and you return to local kimchi. A tab closed by a fatal error stays in the tab bar so you can see the reconnect banner and decide whether to retry or exit.

Copy from the sandbox to your local clipboard

Hold Shift or Option while selecting text to copy it directly to your local clipboard — bypassing the terminal's mouse protocol and any remote clipboard. This is the recommended way to copy from the remote sandbox to your laptop.

Remote programs that emit OSC 52 escape sequences (e.g. tmux with set -g set-clipboard on) also sync their clipboard to your local machine automatically.

Reconnect after a dropped connection

If the WebSocket drops, the overlay shows a status banner and attempts automatic reconnection. The overlay also refreshes the authentication token when it nears expiry, so long-running sessions stay connected without you doing anything.

Resume a session later

From the CLI

Drop back to your local kimchi prompt and run:

/remote-sessions

It opens a full-screen tree panel: each workspace is a top-level row, with its sessions nested underneath (drawn with ├─ / └─ connectors). Columns are NAME / SESSION, STATUS, and LAST ACTIVITY. Navigate with the arrow keys or j / k, then press Enter to reattach.

/remote-sessions replaces the former /sessions and /workspaces commands — workspaces and their sessions are now browsed from a single panel.

Status:

Panel keybindings:

Action keys are context-aware — they apply to whichever kind of row (workspace or session) is selected.

From the Kimchi console

Open the Remote Sessions page in the Kimchi console to see all your active remote sessions and the phase each agent is in (planning, coding, reviewing, done). Click into a session to open its web terminal and interact with the agent directly from the browser.

Open a raw SSH shell

For debugging or running one-off commands outside the PTY overlay, drop into a plain SSH session:

/terminal mybox               # by host nickname or name
/terminal ws-abc12345         # by full workspace ID

/terminal bypasses the overlay and hands your TTY to ssh connected to the sandbox. Type exit or press Ctrl+D to return to local kimchi. The workspace and its sessions keep running.

Workspace limits

• 1 workspace per user, provisioned with 1 CPU and 2 GiB RAM. Delete your old workspace before spinning up a new one if you hit the cap — you can do this from the /remote-sessions panel.
• Workspace size caps — /teleport warns above 500 MB and refuses above 5 GB. Use --force to override the 5 GB refusal, or --exclude (with /sync) to skip large directories like build artifacts, data files, or node_modules/.

Troubleshooting

Dirty working tree

By default /teleport refuses if git status --porcelain shows uncommitted changes — this prevents accidentally shipping work-in-progress. Use --allow-dirty to override.

rsync not found

If rsync isn't on your PATH, /sync and /teleport (in rsync mode) will fail with an install hint. macOS: brew install rsync. Linux: use your package manager (e.g. apt install rsync).

Session not found

If you reference a session that no longer exists, kimchi suggests /remote-sessions to browse what's available. Sessions that have finished and been cleaned up server-side can't be reattached.

Workspace not found

If you reference a workspace that doesn't exist (or that you don't have access to), authentication will fail. Use /remote-sessions to list your available workspaces.

See also

• Ferment — autonomous project mode for multi-step coding work. /teleport works inside Ferment sessions too.
• CLI reference — full command reference for kimchi.
• Getting started with Kimchi Coding — install and run your first session.