Connection

Open a workspace from your terminal or editor over SSH, and reach its tool server.

Last updated 14 Nov 2026

On this page

Overview
Tasks
Connect with SSH
Open the workspace in an editor
Open a tunnel to the tool server
Troubleshooting

Overview

A workspace has no public address. kode opens an authenticated tunnel to it and runs your SSH client through that tunnel.

Interface	Command	Use
Terminal	`kode workspaces ssh`	A shell in the workspace.
Editors and SSH tools	`kode workspaces ssh-config`	Each workspace becomes an SSH host for editors, `scp`, and `rsync`.
Tool server	`kode workspaces ide`	The tool API on a local port.

The SSH user is kd. No SSH key is needed: the tunnel opens only for your CLI login, so the login is the credential. kode pins the workspace's host key and refuses the connection if it changes. If the platform stopped the workspace for idleness, kode starts it and waits up to 180 seconds. ssh and ide take a name, team/name, or an id. ssh-config writes hosts for your own workspaces only.

kode workspaces ssh-config writes ~/.ssh/kode_config, with one host per workspace, and includes it from ~/.ssh/config. Run it again after you create a workspace. Each host uses kode workspaces proxy as its ProxyCommand, so kode must be in the PATH of your editor.

Client	Setting
Terminal	`ssh backend`
VS Code, Cursor	Remote-SSH, host `backend`, folder `/home/kl/workspace`
JetBrains Gateway	SSH, host `backend`, user `kd`, project `/home/kl/workspace`
File copy	`scp ./data.sql backend:workspace/`

A running workspace reaches another workspace of the same owner by its name, for example http://blog-backend:8080. The name stays the same after a restart, so do not copy an IP address.

Tasks

Connect with SSH

Reason for the task

Open a shell in a workspace.

Job set-up

Access: you.
References: kode workspaces ssh.

Procedure

Run the command with the workspace name or id. Put extra SSH options after --, for example -- -A.
CLI
```
kode workspaces ssh backend
```

Close-out

Make sure that whoami prints kd.

Open the workspace in an editor

Reason for the task

Work on the files of a workspace in your editor.

Job set-up

Access: you.
References: kode workspaces ssh-config.

Procedure

Write the SSH configuration.
CLI
```
kode workspaces ssh-config
```
If the output names a directory to add to your PATH, add it.
Open the workspace's host in your editor's remote SSH feature, and open /home/kl/workspace.

Close-out

Make sure that the editor shows the workspace's files.

Open a tunnel to the tool server

Reason for the task

Call the tool API of a workspace from your computer.

Job set-up

Access: you.
References: kode workspaces ide.

Procedure

Start the tunnel and keep it running. Use --port PORT for another local port.
CLI
```
kode workspaces ide backend
```
Run this check from a second terminal.
CLI
```
curl http://localhost:7788/healthz
```

Close-out

Make sure that the output contains "ok":true. Stop the tunnel with Ctrl+C.

Troubleshooting

Symptom	Possible cause	Corrective action
`… is stopped; start it from the console`	You stopped the workspace; `kode` restarts only idle-stopped workspaces.	Start it. See Start a workspace.
`no workspace backend`	No workspace of yours has this name.	Run `kode workspaces list` and use the name or `id` it shows. For a team workspace, use `team/name`.
`… did not become ready:` and a reason	The workspace was not `ready` within 180 seconds.	Read the reason, and show the status.
`503` with `the workspace has not reported its host key yet`	The workspace is still starting.	Wait a few seconds and try again.
`gateway unreachable: HTTP error: 502 Bad Gateway` right after a restart	The workspace is `ready`, but the gateway has not opened the tunnel yet.	Wait five seconds and connect again.
`Connection closed by remote host` from an editor	`kode` is not in the editor's `PATH`.	Add it to `PATH` and restart the editor.