Desk environment

Connect a desk to an environment, change it, or disconnect it.

Last updated 14 Nov 2026

On this page

Overview
Team boundary
Network access
Shared environments
Change and disconnect
Tasks
Connect an environment
Change or disconnect the environment
Troubleshooting
Reach the environment from your computer

Overview

A desk connects to one environment at a time, or to none. While it is connected, every workspace of the desk reaches the services of the environment by name.

Team boundary

A desk connects only to environments of its own team. Teams are isolated from each other.

Desk	Can connect to
Personal, for example `dev`	Your personal environments.
Team, for example `acme/dev`	Every environment of the team `acme`, also those that other members created.

Network access

Direction	Access
Workspace to environment	Each workspace of the desk reaches every service of the environment by name, on the ports that the service lists.
Environment to workspace	Only through an intercept. The traffic of one service goes to a workspace of the desk.
Workspace to workspace	Not given by the desk. A desk gives access to the environment only.

Several desks can connect to the same environment at the same time, from one person or from many. The environment is shared, and each desk keeps its own workspaces. An environment with a connected desk, awake or idle, is in use, so its time to live does not delete it. See Use cases.

Change and disconnect

You can change the environment of a desk at any time. The workspaces stay, and reach the services of the new environment. Changing or disconnecting the environment releases the intercepts of the desk in the old environment. Deleting an environment disconnects its desks and ends none of them.

Tasks

Connect an environment

Reason for the task

Give the desk's workspaces the services of an environment.

Job set-up

Access: you.
References: PUT /v1/desks/{id}/environment, kode desks connect-env.

Procedure

Connect the environment by name or id. kode desks connect-env shop acts on the desk that the laptop last opened, or the one --desk names. An agent connects with desk connect.

Python

kl.desks.connect(desk="dev", environment="shop")

TypeScript

await kl.desks.connect({ desk: "dev", environment: "shop" });

env := "shop"if _, err := kl.Desks.Connect("dev", &env); err != nil {    log.Fatal(err)}

Ruby

kl.desks.connect(desk: "dev", environment: "shop")

Java

kl.desks().connect("dev", "shop");

CLI

kode desks connect-env shop --desk dev

Close-out

Make sure that the desk's environment shows the environment's id.

Change or disconnect the environment

Reason for the task

Move a desk to another environment, or detach it.

Job set-up

Access: you.
References: PUT /v1/desks/{id}/environment, kode desks disconnect-env.

CAUTION

The desk's intercepts in the old environment are released, and their traffic returns to the services.

Procedure

Connect the new environment as in task 001 to change it.

Set the environment to no value to disconnect it. kode desks disconnect-env does the same.

Python

kl.desks.connect(desk="dev", environment=None)

TypeScript

await kl.desks.connect({ desk: "dev", environment: null });

if _, err := kl.Desks.Connect("dev", nil); err != nil {    log.Fatal(err)}

Ruby

kl.desks.connect(desk: "dev", environment: nil)

Java

kl.desks().connect("dev", null);

CLI

kode desks disconnect-env --desk dev

Close-out

Make sure that environment shows the new id, or no value after a disconnect.

Troubleshooting

Symptom	Possible cause	Corrective action
`409` with `that environment is acme's; a desk in karthik connects only to karthik's environments`	The environment belongs to another team.	Connect an environment of the desk's own team.
`409` with `the desk changed; retry`	Another call changed the desk at the same time.	Run the call again.

Reach the environment from your computer

Reason for the task

Use the names of the services of the desk's environment on your own computer.

Job set-up

Access: you.
References: kode status, kode env status, Environment tunnel, Why one password is needed.

The SDK has no tunnel. This task uses the CLI on macOS. kode login asks for your password once, to install the network helper. The helper only edits names and loopback addresses. After --no-root, run kode start later.

A name resolves to an address 127.77.x.y, one for each service. Only TCP is reachable. A port below 1024 is redirected on that address to a port above 60000, so web:80 works as written. Removing the helper also removes its block from the hosts file.

Every other desk of the account gets names too, in the form {service}.{desk}. The bare {service} stays with the selected desk. Each desk has its own addresses, so two desks can both have a web. The tunnel of another desk opens when a connection uses one of its names, and closes after five minutes without one. At most 16 desks get names. kode status lists each desk with its services, and the desks that got no names.

Procedure

Run the login, which sets up the background service and the network helper.
CLI
```
kode login
```
Select the desk as in task 001 of its page, and connect an environment to it.
Show the state of the tunnel and of the helper. The output lists each service with its loopback address and ports.
CLI
```
kode status
```
Use a service name, for example mongodb://db:27017, in a program on your computer.
Remove the network helper when you no longer need the tunnel, with the uninstall line of the reference.

Close-out

Make sure that kode status shows tunnel: up and the environment that you connected.