Session sandboxes

Run short-lived sandboxes in a session, so that their command reaches the services of its environment.

Last updated 25 Oct 2026

On this page

Description and operation
General
Environment access
Use with workspaces
Quota
Tasks
Run a sandbox in a session
Troubleshooting

A sandbox is a short-lived, isolated machine that runs one command. See Sandboxes. A sandbox created through a session is part of that session from its start. The session manages it, like the other workspaces of the session.

Item	Sandbox in a session
Created	Through the session, with `sessions create-sandbox`.
Environment	The services of the session environment resolve by name inside the sandbox. A session is the only way to reach an environment.
Use	A running sandbox keeps the session in use.
Ended	When its command exits, at its time limit, by an end request, or when the session ends. It cannot start again.
Direct control	Refused with `409`. Use the session.

A sandbox is for one run. It is not stopped or started with the session. It runs until it ends, and its files are gone with it. An ended sandbox cannot start again. To run again, create a new sandbox.

Environment access

A sandbox reaches the environment that the session is connected to. A sandbox created from a copy of a workspace does not inherit the session of that workspace.

A sandbox does not intercept services. Only a workspace takes over a service. See Intercepts.

Use with workspaces

Task	Workspace	Sandbox
Edit code and keep it	Yes. The home is kept.	No. Files are gone at the end.
Run a test or a script against the services	Yes.	Yes. The script is the command.
Run many runs in parallel	Slow to prepare.	Yes. Each run has its own new sandbox.
Receive the traffic of a service	Yes, with an intercept.	No.

Access: you, as the owner of the session.
Conditions: the session has an environment. See Connect an environment.
References: POST /v1/sessions/{id}/sandboxes.

Procedure

Create the sandbox through the session. The team is the team of the session.

Python

sb = kl.sessions.create_sandbox(session="acme/review", cmd=["python3", "test.py"], timeout_s=600)

TypeScript

const sb = await kl.sessions.createSandbox({ session: "acme/review", cmd: ["python3", "test.py"], timeoutS: 600 });

sb, err := kl.Sessions.CreateSandbox(kloudlite.CreateSessionSandbox{Session: "acme/review", CreateSandbox: kloudlite.CreateSandbox{Cmd: []string{"python3", "test.py"}, Timeout: 600 * time.Second}})if err != nil {    log.Fatal(err)}

Ruby

sb = kl.sessions.create_sandbox(session: "acme/review", cmd: ["python3", "test.py"], timeout_s: 600)

Java

var sb = kl.sessions().createSandbox("acme/review", new Kloudlite.CreateSandbox().cmd(List.of("python3", "test.py")).timeout(Duration.ofSeconds(600)));

CLI

kloudlite sessions create-sandbox --session acme/review --timeout-s 600 -- python3 test.py

Wait for the command to exit, then read its output as in Run a command.

Close-out

Make sure that the sandbox is in the list of the session's workspaces.
Make sure that the sandbox ends when the command exits, at its time limit or with the session.

Troubleshooting

Symptom	Possible cause	Corrective action
`409` with `{id} is managed by session {name}; use the session`	The call ends or deletes a sandbox that belongs to a session.	End the session, or wait for the time limit of the sandbox.
A service name does not resolve in the sandbox	The session has no environment, or the environment is stopped.	Connect an environment to the session. Wait until the environment runs.
The sandbox is `terminated` and does not answer	A sandbox runs once. The command, a time limit, an end request or the end of the session ended it.	Create a new sandbox.
`422` with `create a session's sandbox with POST /v1/sessions/{id}/sandboxes`	The call is `POST /v1/sandboxes` with `session`.	Create the sandbox through the session, as in the task above.
`404` with `not found` for `session`	The session is not yours, or is in another team.	Check the name. Use `team/name` for a team.