Environment

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

Last updated 24 Oct 2026

On this page

Description and operation
General
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

Description and operation

General

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

Team boundary

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

Session	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 session 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 session.
Workspace to workspace	Not given by the session. A session gives access to the environment only.

Several sessions can connect to the same environment at the same time, from one person or from many. The environment is shared, and each session keeps its own workspaces. An environment with a connected session, 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 session at any time. The workspaces stay, and reach the services of the new environment. Changing or disconnecting the environment releases the intercepts of the session in the old environment. Deleting an environment disconnects its sessions and ends none of them.

Tasks

Connect an environment

Reason for the task: Give the session's workspaces the services of an environment.

Job set-up

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

Procedure

Connect the environment by name or id. kloudlite sessions connect-env shop acts on the selected session.

Python

kl.sessions.connect(session="dev", environment="shop")

TypeScript

await kl.sessions.connect({ session: "dev", environment: "shop" });

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

Ruby

kl.sessions.connect(session: "dev", environment: "shop")

Java

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

CLI

kloudlite sessions connect-env shop --session dev

Close-out

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

Change or disconnect the environment

Reason for the task: Move a session to another environment, or detach it.

Job set-up

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

CAUTION

The session'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. kloudlite sessions disconnect-env does the same.

Python

kl.sessions.connect(session="dev", environment=None)

TypeScript

await kl.sessions.connect({ session: "dev", environment: null });

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

Ruby

kl.sessions.connect(session: "dev", environment: nil)

Java

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

CLI

kloudlite sessions disconnect-env --session 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 session in karthik connects only to karthik's environments`	The environment belongs to another team.	Connect an environment of the session's own team.
`409` with `the session changed; retry`	Another call changed the session 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 session's environment on your own computer.

Job set-up

Access: you.
References: kloudlite env, kloudlite env status, kloudlite env daemon install, kloudlite env daemon uninstall.

The SDK has no tunnel. This task uses the CLI on macOS and needs sudo.

Procedure

Select the session as in task 001 of its page, and connect an environment to it.
Install the background daemon.
CLI
```
sudo kloudlite env daemon install
```
Show the state of the daemon. The output shows the environment, the state of the tunnel and the names in the hosts block.
CLI
```
kloudlite env status
```
Use a service name, for example mongodb://db:27017, in a program on your computer.
Remove the daemon when you no longer need the tunnel. This stops the daemon and removes its hosts block.
CLI
```
sudo kloudlite env daemon uninstall
```

Close-out

Make sure that kloudlite env status shows the environment that you connected.