Desks

Overview

A desk groups your workspaces and capsules and connects them to an environment. It joins a set of workspaces to one environment, so that each workspace reaches the services of the environment by name, for example postgres://db:5432. Code in a workspace runs against the real dependencies of the application, with no local set-up.

A desk belongs to the person who creates it, in their personal team or in a team. Other members of the team cannot see or change it. They work in their own desks, which can connect to the same environment.

Desks let several developers work on one environment at the same time, each in their own desk. See Use cases.

A desk has a name: name for a personal desk, team/name for a team desk. Its id starts with desk-.

The runtime

A desk has no machine of its own. The Kode runtime serves every desk. It is a service of the region, and it keeps the conversation of each desk in storage. A desk is always ready to take a message.

The kode program and the harness reach the runtime through the tunnel of the desk. An MCP client reaches it through kode mcp. A message that arrives while the runtime is busy waits in the queue of the desk.

Read the queue with GET /v1/desks/{id}/queue. pending is the number of messages not yet handled. failed is the number that the runtime gave up on after five attempts over about 85 seconds. POST /v1/desks/{id}/queue/replay puts them back in the queue. A desk with failed above 0 shows the reason N messages failed; see the queue.

States

Lifecycle

• Use. A desk is in use while a client is connected, a message is being handled, or an environment tunnel carries data. It is also in use while any of its workspaces is in use: an SSH connection, a tool request, or a running capsule. A detached process does not count.
• Idle stop. After 30 minutes without use, the desk is idle and its workspaces stop, with idle_since set. Its environment stops 5 minutes later, unless another awake desk is connected to it.
• Wake. Starting a workspace of the desk, creating a workspace in it, connecting an environment, or sending a hold wakes the desk and its environment. A wake never starts a resource that you stopped yourself.
• Stop. Stopping a desk stops all its workspaces. Their homes are kept. Start the desk again with kode desks start.
• Time to live. The platform deletes a desk that is not used for ttl_secs (600 to 2592000). An awake desk never expires.
• Delete. Deleting a desk releases its intercepts and deletes its workspaces. Their snapshots and the environment remain.

Quota and limits

A desk uses no vCPU, memory, or disk from the owner's quota. Its workspaces and its environment count separately.

The live page

The live page shows what a desk holds, read only. Open it from the desk in the console, at /{owner}/desks/{id}/live. A sidebar on the left lists the desk, its workspaces, its capsules, and its environment with each service. Select one item and the page shows it with its own header.

A workspace shows the workspace live page: its tasks, its tool calls, its files, and its running processes. A capsule shows its logs and its exit state. The environment shows its volume snapshot and a table of services. A service shows its state, its ports, which workspace intercepts it, and whether it needs a restart. Each link keeps the selection, so you can share the address of one item.

Only the owner of the desk sees the page, and it has no control that changes anything. Opening the page never wakes a desk and never keeps it awake. A stopped desk shows kode desks start --desk NAME. A stopped workspace, a capsule that ended, and an environment that is down still show, from stored records.

If a workspace does not answer, its row shows a sentence that explains why. The rest of the page still loads. A desk with no workspaces or no environment shows an empty state that names the next step. An unknown desk id shows a 404 page.

Tasks

Create a desk

Reason for the task

Start a working context for your workspaces.

Job set-up

• Access: you.
• References: POST /v1/desks.

Procedure

1. Create the desk. Use team/name for a team desk, and set environment to connect one at once.

   PythonCopy

   from kloudlite import Kodekl = Kloudlite()x = kl.desks.create(desk="dev", environment="shop")print(x["id"])

   TypeScriptCopy

   import { Kode } from "./index.ts";const kl = new Kloudlite();const x: any = await kl.desks.create({ desk: "dev", environment: "shop" });console.log(x.id);

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})x, err := kl.Desks.Create(kloudlite.CreateDesk{Desk: "dev", Environment: "shop"})if err != nil {    log.Fatal(err)}fmt.Println(x["id"])

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newputs kl.desks.create(desk: "dev", environment: "shop")["id"]

   JavaCopy

   var kl = new Kloudlite();System.out.println(kl.desks().create(new Kloudlite.CreateDesk().desk("dev").environment("shop")));

   CLICopy

   kode desks create dev --environment shop

Close-out

1. Make sure that the desk is in kode desks list.

Keep a desk awake

Reason for the task

Prevent an idle stop while you work outside kode and the desk.

Job set-up

• Access: you.
• References: POST /v1/desks/{id}/hold.

Procedure

1. Send a hold for the desk, and repeat it at least every 60 seconds. The response is 204.

   PythonCopy

   sid = kl.desks.get(desk="dev")["id"]kl.request("POST", f"/v1/desks/{sid}/hold")

   TypeScriptCopy

   const sid: string = ((await kl.desks.get({ desk: "dev" })) as any).id;await kl.request("POST", `/v1/desks/${sid}/hold`);

   GoCopy

   s, err := kl.Desks.Get("dev")if err != nil {    log.Fatal(err)}if err := kl.Request("POST", "/v1/desks/"+s["id"].(string)+"/hold", kloudlite.RequestOptions{}); err != nil {    log.Fatal(err)}

   RubyCopy

   sid = kl.desks.get(desk: "dev")["id"]kl.request("POST", "/v1/desks/#{sid}/hold")

   JavaCopy

   // The client returns raw JSON; read "id" with your JSON library.var s = kl.desks().get("dev");int k = s.indexOf("\"id\":\"") + 6;kl.request("POST", "/v1/desks/" + s.substring(k, s.indexOf('"', k)) + "/hold");

   CLICopy

   kode request POST /v1/desks/$(kode desks get dev --json | jq -r .id)/hold

Close-out

1. Make sure that the desk's workspaces are not stopped.

Set the time to live

Reason for the task

Delete a desk automatically after a period without use.

Job set-up

• Access: you.
• References: PUT /v1/desks/{id}/ttl.

Procedure

1. Set ttl_secs from 600 to 2592000. Set it to no value (None, null, nil) to clear it.

   PythonCopy

   kl.desks.set_ttl(desk="dev", ttl_secs=86400)

   TypeScriptCopy

   await kl.desks.setTtl({ desk: "dev", ttlSecs: 86400 });

   GoCopy

   ttl := int64(86400)if _, err := kl.Desks.SetTTL("dev", &ttl); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.desks.set_ttl(desk: "dev", ttl_secs: 86400)

   JavaCopy

   kl.desks().setTtl("dev", 86400L);

   CLICopy

   kode desks set-ttl dev --ttl-secs 86400

Close-out

1. Make sure that expires_at shows a time, or no value if you cleared it.

Stop a desk

Reason for the task

Release the compute of a desk and keep its data.

Job set-up

• Access: you.
• References: POST /v1/desks/{id}/stop.

Procedure

1. Stop the desk. Use team/name for a team desk.

   PythonCopy

   kl.desks.stop(desk="dev")

   TypeScriptCopy

   await kl.desks.stop({ desk: "dev" });

   GoCopy

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

   RubyCopy

   kl.desks.stop(desk: "dev")

   JavaCopy

   kl.desks().stop("dev");

   CLICopy

   kode desks stop --desk dev

Close-out

1. Make sure that the desk and its workspaces show stopped.

Delete a desk

Reason for the task

Remove a desk that you no longer need.

Job set-up

• Access: you.
• References: DELETE /v1/desks/{id}.

Procedure

1. Delete the desk.

   PythonCopy

   kl.desks.delete(desk="dev")

   TypeScriptCopy

   await kl.desks.delete({ desk: "dev" });

   GoCopy

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

   RubyCopy

   kl.desks.delete(desk: "dev")

   JavaCopy

   kl.desks().delete("dev");

   CLICopy

   kode desks delete dev

Close-out

1. Make sure that the desk is no longer in kode desks list.

List desks

Reason for the task

Find the desks that you can use.

Job set-up

• Access: you.
• References: GET /v1/desks, kode desks list.

Procedure

1. Show the list. Pass a team to list the desks of that team.

   PythonCopy

   print(kl.desks.list())

   TypeScriptCopy

   console.log(await kl.desks.list());

   GoCopy

   list, err := kl.Desks.List("")if err != nil {    log.Fatal(err)}fmt.Println(list)

   RubyCopy

   p kl.desks.list

   JavaCopy

   System.out.println(kl.desks().list(null));

   CLICopy

   kode desks list

Close-out

1. Make sure that each desk that you expect is listed.

Start a desk

Reason for the task

Run the environment and workspaces of a stopped or idle desk again.

Job set-up

• Access: you.
• References: POST /v1/desks/{id}/start, kode desks start.

Procedure

1. Start the desk. Use team/name for a team desk.

   PythonCopy

   kl.desks.start(desk="dev")

   TypeScriptCopy

   await kl.desks.start({ desk: "dev" });

   GoCopy

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

   RubyCopy

   kl.desks.start(desk: "dev")

   JavaCopy

   kl.desks().start("dev");

   CLICopy

   kode desks start --desk dev

Close-out

1. Make sure that the workspaces of the desk show running.

Troubleshooting