Connection

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

Last updated 23 Oct 2026

On this page

Description and operation
General
Tasks
Connect with SSH
Open the workspace in an editor
Open a tunnel to the tool server
Troubleshooting

Description and operation

General

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

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

The SSH user is kl. No SSH key is needed: the tunnel opens only for your CLI login, so the login is the credential. kloudlite pins the workspace's host key and refuses the connection if it changes. If the platform stopped the workspace for idleness, kloudlite 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.

kloudlite workspaces ssh-config writes ~/.ssh/kloudlite_config, with one host per workspace, and includes it from ~/.ssh/config. Run it again after you create a workspace. Each host uses kloudlite workspaces proxy as its ProxyCommand, so kloudlite 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 `kl`, project `/home/kl/workspace`
File copy	`scp ./data.sql backend:workspace/`

Tasks

Connect with SSH

Reason for the task: Open a shell in a workspace.

Job set-up

Access: you.
References: kloudlite workspaces ssh.

Procedure

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

Close-out

Make sure that whoami prints kl.

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: kloudlite workspaces ssh-config.

Procedure

Write the SSH configuration.
CLI
```
kloudlite 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: kloudlite workspaces ide.

Procedure

Start the tunnel and keep it running. Use --port PORT for another local port.
CLI
```
kloudlite 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; `kloudlite` restarts only idle-stopped workspaces.	Start it. See Start a workspace.
`no workspace backend`	No workspace of yours has this name.	Run `kloudlite 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.
`Connection closed by remote host` from an editor	`kloudlite` is not in the editor's `PATH`.	Add it to `PATH` and restart the editor.