Desk capsules

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

Last updated 14 Nov 2026

On this page

Overview
Environment access
Use with workspaces
Quota
Tasks
Run a capsule in a desk
Troubleshooting

Overview

A capsule is a disposable container that runs one command or one shell and is deleted when it exits. See Capsules. A capsule created through a desk is part of that desk from its start. The desk manages it, like the other workspaces of the desk.

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

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

Environment access

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

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

Use with workspaces

Task	Workspace	Capsule
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 capsule.
Receive the traffic of a service	Yes, with an intercept.	No.

Reason for the task

Run a command that needs the services of the desk environment, without a workspace.

Job set-up

Access: you, as the owner of the desk.
Conditions: the desk has an environment. See Connect an environment.
References: POST /v1/desks/{id}/capsules.

Procedure

Create the capsule through the desk. The team is the team of the desk.

Python

sb = kl.desks.create_capsule(desk="acme/review", cmd=["python3", "test.py"], timeout_s=600)

TypeScript

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

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

Ruby

sb = kl.desks.create_capsule(desk: "acme/review", cmd: ["python3", "test.py"], timeout_s: 600)

Java

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

CLI

kode desks create-capsule --desk 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 capsule is in the list of the desk's workspaces.
Make sure that the capsule ends when the command exits, at its time limit, or with the desk.

Troubleshooting

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