Remote Workspaces

Remote Workspaces are centralized, cloud-based sandboxes for your Kimchi Coding work. They give you a persistent place to run sessions when you close your laptop, switch machines, or need to leave work running.

Each user can have one Remote Workspace. It is provisioned with 2 CPUs, 8 GB of RAM, and 20 GB of disk space.

A workspace can contain multiple agent sessions. You can start work locally and hand an in-progress session to the cloud with /teleport, or use Start execution in cloud to run an approved plan remotely. Reconnect from the CLI, the Kimchi console, the Web IDE, or VS Code when you are ready to continue.

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

Prerequisites

Before you start

• Start a Kimchi Coding session in your local kimchi CLI or inside a Ferment plan.
• Use a Remote Workspace for work that will take long enough that you may close your laptop, switch context, or return later.
• Ensure that the project files you need are in your working directory before using /teleport.

Workspaces and sessions

A workspace is the cloud sandbox where your work runs. A session is one agent run inside that workspace.

A single workspace can host multiple sessions at the same time. Tab between them with Ctrl+B c, Ctrl+B n, or Ctrl+B p, or browse all sessions in a workspace with /remote-sessions.

Group related sessions in the same workspace when they share a project or repository. For example, you can run different investigations in parallel, open a second session to inspect a failing build, or hand a task from one agent to another.

Sessions in the same workspace share files and workspace state. Because each user has one workspace, reuse it for related work instead of treating each session as a separate sandbox.

Remote Execution

Remote Execution runs an approved plan in your Remote Workspace instead of on your local machine. When Kimchi asks you to approve a plan or To-Do, select Execute the plan in a remote workspace.

Kimchi starts the approved work remotely, so the agent can continue after you close your laptop, leave the local session, or move to another device.

Control Remote Execution

Remote Execution is enabled by default. Set KIMCHI_REMOTE_RUN=0 to disable Start execution in cloud and keep plan execution local.

KIMCHI_REMOTE_RUN=0 kimchi --plan

For the complete command and approval-menu reference, see the TUI reference.

Hand off your session to the cloud

Use /teleport to move an in-progress local Kimchi Coding session into your Remote Workspace.

The remote agent keeps running when you close your laptop, switch machines, or hand work to a teammate. Your workspace and session remain available so that you can reconnect later.

/teleport flags

Beyond the default /teleport, these flags cover common cases:

Examples:

/teleport --workspace mybox task-2
/teleport --git-repo https://github.com/org/repo.git --branch main
/teleport --allow-dirty

You can also pass an optional positional name to label the session:

/teleport my-feature

Allowed characters are letters, digits, -, and _. Names must be unique within a workspace.

Git credentials

When /teleport detects a Git remote, such as github.com, it prompts for a personal access token. The token is forwarded to the sandbox so the remote agent can pull from and push to 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 are not prompted again for the same host.
• Skip — Press Esc to continue without Git credentials. The remote workspace will not be able to access private repositories.

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 full-screen terminal multiplexer on the remote sandbox. Your session, tools, files, and agent state are already there.

Keep typing, run commands, inspect files, 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 in the same workspace. Use tabs to run a second parallel task or inspect the environment while another agent is working.

Sessions are long-lived. They continue running on the server after you disconnect, so you can return later and resume where you left off.

Tabs are lazy by default. Their WebSocket opens only when you switch to them, which keeps socket usage low.

The first tab you open through /teleport is eager and stays connected. The chord state resets after one operand, and unknown operands are silently consumed so they do not leak into the active shell.

Tab indicators

Push local changes without restarting

If you make local changes after 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 Remote Workspace:

• up transfers files from local to remote.
• down transfers files from remote to local.

Both directions require --workspace, --source, and --target.

Default exclusions for directory transfers are:

node_modules/
dist/
.next/
target/
__pycache__/
.venv/
.env*
*.log
.DS_Store
.kimchi/

Git-ignored entries are also excluded unless you set --include-ignored.

Single-file transfers skip these default exclusions and use only 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 VS Code

Run /ssh-config inside the overlay, then select VS Code → Remote Sessions.

The workspace appears automatically and you can connect directly to the remote filesystem. No manual ~/.ssh/config edits are required.

You get a full editor pointed at the workspace while the agent continues working in the overlay.

Exit the overlay

Press Ctrl+D to return to your local kimchi prompt.

The Remote Workspace, session, and agent continue running.

When a session terminates normally, for example when you type exit in the shell, its tab closes. If it was the last tab, the overlay closes and you return to local Kimchi.

A tab closed by a fatal error remains 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.

This bypasses the terminal mouse protocol and any remote clipboard.

Remote programs that emit OSC 52 escape sequences, such as 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 to reconnect automatically.

The overlay also refreshes the authentication token when it nears expiry, so long-running sessions remain connected without intervention.

Resume a session later

From the CLI

Return 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 using ├─ and └─ connectors.

The columns are NAME / SESSION, STATUS, and LAST ACTIVITY.

Navigate with the arrow keys or j and k, then press Enter to reattach.

/remote-sessions replaces the former /sessions and /workspaces commands. Workspaces and their sessions are now browsed from one panel.

Session status

Panel keybindings

Action keys are context-aware: they apply to the selected workspace or session row.

From the Kimchi console

Open the Remote Sessions page in the Kimchi console to see your active remote sessions and the phase each agent is in:

• Planning
• Coding
• Reviewing
• Done

Click a session to open its web terminal and interact with the agent from the browser.

Next to the web terminal, open the workspace in the Web IDE — a full browser-based IDE with the Kimchi VS Code extension preinstalled.

Open a raw SSH shell

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

/terminal mybox
/terminal ws-abc12345

Use a host nickname, workspace name, or full workspace ID.

/terminal bypasses the overlay and hands your TTY to ssh connected to the Remote Workspace.

Type exit or press Ctrl+D to return to local Kimchi. The workspace and its sessions keep running.

Workspace limits

• One workspace per user — Your Remote Workspace is provisioned with 2 CPUs, 8 GB of RAM, and 20 GB of disk space. Delete the existing workspace from the /remote-sessions panel before creating another workspace if you need a clean environment.
• Transfer-size caps — /teleport warns above 500 MB and refuses transfers above 5 GB. Use --force to override the 5 GB refusal.
• Disk allocation and transfer size are separate — A workspace has 20 GB of disk space, but /teleport still applies the 5 GB transfer limit to prevent large initial uploads.
• Large repositories — Use --exclude with /sync to skip large directories such as build artifacts, generated files, datasets, and node_modules/.

Troubleshooting

Dirty working tree

By default, /teleport refuses when git status --porcelain shows uncommitted changes.

This prevents accidentally shipping work in progress.

Use --allow-dirty to override the check:

/teleport --allow-dirty

rsync not found

If rsync is not on your PATH, /sync and /teleport in rsync mode fail with an installation hint.

On macOS:

brew install rsync

On Linux, install it with your package manager:

apt install rsync

Session not found

If you reference a session that no longer exists, Kimchi suggests /remote-sessions so you can browse available sessions.

You cannot reattach to sessions that finished and were cleaned up server-side.

Workspace not found

If you reference a workspace that does not exist, or that you cannot access, authentication fails.

Use /remote-sessions to list your available workspaces.

See also

• Create and Use a Remote Workspace — Step-by-step developer journey: create a workspace from a template, connect, and reconnect later.
• Web IDE — A full browser-based IDE for your Remote Workspace, with the Kimchi VS Code extension preinstalled.
• Audit Log — Every change to your workspaces and workspace templates, recorded with who made it and what changed.
• Ferment — Autonomous project mode for multi-step coding work. /teleport also works inside Ferment sessions.
• TUI reference — Full command reference for kimchi.
• Getting started with Kimchi Coding — Install Kimchi and run your first session.