Workspaces

Overview

A workspace is your sandbox: an isolated machine that is kept while it is stopped. You start it, stop it, and connect to it, with your packages and SSH access. Its home is kept until you delete the workspace. It has the parts of an IDE without the window: a file system, a toolchain, a terminal, processes, and git. You open the same workspace from your terminal or editor over SSH.

Each workspace has its own kernel, file system, and network stack, with allocated vCPU, memory, and disk. A workspace belongs to you or to a team. Its name is unique for that owner, and the platform also gives it an id that starts with ws-.

Workspace and capsule

Other platforms use the word sandbox for an isolated machine that keeps its files while work continues. In Kode, that machine is a workspace. A capsule is a different object: a short-lived container for one command.

To do these tasks with an AI agent, see Agentic workflows.

Workspace types

A workspace is standalone or managed. The type is set at creation and does not change.

A standalone workspace cannot join a desk later. To work with an environment, create a managed workspace in a desk.

Creation parameters

States

The state also has packages_status (installation progress), placed (NoCapacity while the platform has no room), degraded (StorageUnavailable while its storage moves), idle_since, and expires_at.

Lifecycle

• In a desk. A workspace in a desk is controlled through its desk. Starting or stopping the desk starts or stops it, and deleting the desk deletes it. Its desk field names the desk.
• Stop. All processes end and the home is kept. Detached processes started through the tool server start again with the workspace.
• Idle stop. A workspace in a desk stops when the desk is idle. Any other workspace stops after 30 minutes without use. An SSH connection or a tool server request counts as use. Using an idle-stopped workspace starts it again; a workspace that you stopped stays stopped.
• Machine loss. If the machine that runs a workspace fails or is reclaimed, the platform starts the workspace on another machine. Processes and memory are lost. Data that the workspace synced to disk is kept. Detached processes start again.
• Storage failure. If a storage machine fails, the storage serves the home from its second copy and the workspace keeps running.
• Time to live. The platform deletes a workspace that is unused for ttl_secs (600 to 2592000). A running workspace, or one whose desk is awake, is never deleted.
• Delete. The workspace and its home are removed. Snapshots stay.

Clone

A clone is a new workspace that starts with a copy of the live state of a workspace. The platform makes the copy at the time of the request, also while the source runs. A clone is not a snapshot, and it does not change the snapshot lineage.

The copy is independent: changes in the clone do not change the source, and changes in the source do not change the clone. The clone call answers 202 and starts the new workspace at once. The new workspace has the team and the region of its source, and it uses the same volume.

The answer has the field based_on. It names the copy that the clone started from.

The copy shares its data with the source until either changes, so a clone of a large home is quick.

A clone counts as a new workspace against the quota of the owner.

To do these tasks with an AI agent, see Agentic workflows.

Restore

A restore makes a new workspace from a snapshot of a workspace. You name the snapshot by a reference: a volume name, name@N, or the id of a snapshot. The snapshot must be ready. To restore a volume of a team, give the team. A volume of another owner is never restored: the call answers 404. A restore moves the expiry of the snapshot to a full default lifetime from now.

The new workspace is on the volume of the snapshot. The source workspace can be deleted. A restore then attaches the detached volume again.

The new workspace takes the definition that the snapshot froze: image, packages, locks, and resources. A value in the request replaces the frozen value. An unchanged package keeps its lock, and a new pinned package is resolved.

The new workspace belongs to you. It is in the team of the source while the source exists, else it is personal. It is in no desk, has no variables, and no time to live.

A restore counts as a new workspace against the quota of its owner. It is refused when the disk of the owner is already above diskGb.

Quota and limits

A running workspace counts its disk, 4 vCPU, and 8 GB of memory against the owner's quota. A stopped workspace counts only its disk.

Tasks

Create a workspace

Reason for the task

Get a new workspace to work in.

Job set-up

• Access: you. A team workspace needs team membership.
• References: POST /v1/workspaces.

Procedure

1. Create the workspace. Add packages, repo, and branch as needed.

   PythonCopy

   from kloudlite import Kodekl = Kloudlite()ws = kl.workspaces.create(workspace="backend")print(ws["id"], ws["state"])

   TypeScriptCopy

   import { Kode } from "./index.ts";const kl = new Kloudlite();const ws: any = await kl.workspaces.create({ workspace: "backend" });console.log(ws.id, ws.state);

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})ws, err := kl.Workspaces.Create(kloudlite.CreateWorkspace{Workspace: "backend", QuotaGb: 20})if err != nil {    log.Fatal(err)}fmt.Println(ws["id"], ws["state"])

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newws = kl.workspaces.create(workspace: "backend")puts "#{ws['id']} #{ws['state']}"

   JavaCopy

   var kl = new Kloudlite();System.out.println(kl.workspaces().create(new Kloudlite.CreateWorkspace().workspace("backend")));

   CLICopy

   kode workspaces create backend

Close-out

1. Show the status as in task 002. Wait until state is ready.

Show the status of a workspace

Reason for the task

Check whether a workspace runs, and why not.

Job set-up

• Access: you.
• References: GET /v1/workspaces/{id}.

Procedure

1. Show the workspace.

   PythonCopy

   ws = kl.workspaces.get(workspace="backend")print(ws["state"], ws["packages_status"], ws["placed"], ws["degraded"])

   TypeScriptCopy

   const ws: any = await kl.workspaces.get({ workspace: "backend" });console.log(ws.state, ws.packages_status, ws.placed, ws.degraded);

   GoCopy

   ws, err := kl.Workspaces.Get("backend")if err != nil {    log.Fatal(err)}fmt.Println(ws["state"], ws["packages_status"], ws["placed"], ws["degraded"])

   RubyCopy

   ws = kl.workspaces.get(workspace: "backend")puts [ws["state"], ws["packages_status"], ws["placed"], ws["degraded"]].join(" ")

   JavaCopy

   System.out.println(kl.workspaces().get("backend"));

   CLICopy

   kode workspaces get backend

Close-out

1. Make sure that state is what you expect. If not, see Troubleshooting.

Start a workspace

Reason for the task

Run a stopped workspace.

Job set-up

• Access: you.
• References: POST /v1/workspaces/{id}/start.

Procedure

1. Start the workspace.

   PythonCopy

   kl.workspaces.start(workspace="backend")

   TypeScriptCopy

   await kl.workspaces.start({ workspace: "backend" });

   GoCopy

   if err := kl.Workspaces.Start("backend"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.workspaces.start(workspace: "backend")

   JavaCopy

   kl.workspaces().start("backend");

   CLICopy

   kode workspaces start backend

Close-out

1. Show the status as in task 002. Wait until state is ready.

Stop a workspace

Reason for the task

Release the compute of a workspace and keep its home.

Job set-up

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

Procedure

1. Stop the workspace.

   PythonCopy

   kl.workspaces.stop(workspace="backend")

   TypeScriptCopy

   await kl.workspaces.stop({ workspace: "backend" });

   GoCopy

   if err := kl.Workspaces.Stop("backend"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.workspaces.stop(workspace: "backend")

   JavaCopy

   kl.workspaces().stop("backend");

   CLICopy

   kode workspaces stop backend

Close-out

1. Show the status as in task 002. Make sure that state is stopped.

Set the time to live

Reason for the task

Delete a workspace automatically after a period without use.

Job set-up

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

Procedure

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

   PythonCopy

   kl.workspaces.set_ttl(workspace="backend", ttl_secs=86400)

   TypeScriptCopy

   await kl.workspaces.setTtl({ workspace: "backend", ttlSecs: 86400 });

   GoCopy

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

   RubyCopy

   kl.workspaces.set_ttl(workspace: "backend", ttl_secs: 86400)

   JavaCopy

   kl.workspaces().setTtl("backend", 86400L);

   CLICopy

   kode workspaces set-ttl backend --ttl-secs 86400

Close-out

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

Delete a workspace

Reason for the task

Remove a workspace that you no longer need.

Job set-up

• Access: you.
• References: DELETE /v1/workspaces/{id}, Take a snapshot of a workspace.

Procedure

1. Delete the workspace.

   PythonCopy

   kl.workspaces.delete(workspace="backend")

   TypeScriptCopy

   await kl.workspaces.delete({ workspace: "backend" });

   GoCopy

   if err := kl.Request("DELETE", "/v1/workspaces/backend", kloudlite.RequestOptions{}); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.workspaces.delete(workspace: "backend")

   JavaCopy

   kl.workspaces().delete("backend");

   CLICopy

   kode workspaces delete backend

Close-out

1. Make sure that state is deleted.

List workspaces

Reason for the task

Find the workspaces that you can use.

Job set-up

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

Procedure

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

   PythonCopy

   print(kl.workspaces.list())

   TypeScriptCopy

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

   GoCopy

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

   RubyCopy

   p kl.workspaces.list

   JavaCopy

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

   CLICopy

   kode workspaces list

Close-out

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

Clone a workspace

Reason for the task

Create a new workspace that starts with a copy of the files of a workspace.

Job set-up

• Access: you. A team workspace needs team membership.
• References: POST /v1/workspaces/{id}/clone.

Procedure

1. Clone the workspace. Use a free name for to.

   PythonCopy

   new = kl.workspaces.clone(workspace="backend", to="api-experiment", task="try the new parser")print(new["id"], new["state"], new["based_on"])

   TypeScriptCopy

   const created = (await kl.workspaces.clone({ workspace: "backend", to: "api-experiment", task: "try the new parser" })) as Record<string, unknown>;console.log(created.id, created.state, created.based_on);

   GoCopy

   created, err := kl.Workspaces.Clone(kloudlite.CloneWorkspace{Workspace: "backend", To: "api-experiment", Task: "try the new parser"})if err != nil {    log.Fatal(err)}fmt.Println(created["id"], created["state"], created["based_on"])

   RubyCopy

   created = kl.workspaces.clone(workspace: "backend", to: "api-experiment", task: "try the new parser")puts created.values_at("id", "state", "based_on").join(" ")

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String created = kl.workspaces().clone(new Kloudlite.CloneWorkspace().workspace("backend").to("api-experiment").task("try the new parser"));System.out.println(created);

   CLICopy

   kode workspaces clone backend --to api-experiment --task "try the new parser"

Close-out

1. Read based_on. Write down snapshot, the copy that the clone started from.
2. Wait until the state of the new workspace is ready.

Restore a workspace from a snapshot

Reason for the task

Create a new workspace from the state that a snapshot froze.

Job set-up

• Access: you. A team snapshot needs team membership.
• Conditions: you know the id of a ready snapshot of a workspace. See List the lineage.
• References: POST /v1/workspaces/restore.

Procedure

1. Restore the workspace. Use the id for snapshot, and a free name for to.

   PythonCopy

   new = kl.workspaces.restore(snapshot="ws-0a1b2c3d4e5f6a7b-8a7b6c5d", to="api-restored")print(new["id"], new["state"])

   TypeScriptCopy

   const created = (await kl.workspaces.restore({ snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d", to: "api-restored" })) as Record<string, unknown>;console.log(created.id, created.state);

   GoCopy

   created, err := kl.Workspaces.Restore(kloudlite.RestoreWorkspace{Snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d", To: "api-restored"})if err != nil {    log.Fatal(err)}fmt.Println(created["id"], created["state"])

   RubyCopy

   created = kl.workspaces.restore(snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d", to: "api-restored")puts created.values_at("id", "state").join(" ")

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String created = kl.workspaces().restore(new Kloudlite.RestoreWorkspace().snapshot("ws-0a1b2c3d4e5f6a7b-8a7b6c5d").to("api-restored"));System.out.println(created);

   CLICopy

   kode workspaces restore --snapshot ws-0a1b2c3d4e5f6a7b-8a7b6c5d --to api-restored

2. Add image, or packages to the call in step 1 to replace a frozen value. In the CLI, add --image, or --package.

   PythonCopy

   new = kl.workspaces.restore(snapshot="ws-0a1b2c3d4e5f6a7b-8a7b6c5d", to="api-restored", packages=["ripgrep", "nodejs@20"])print(new["id"], new["state"])

   TypeScriptCopy

   const created = (await kl.workspaces.restore({  snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d",  to: "api-restored",  packages: ["ripgrep", "nodejs@20"],})) as Record<string, unknown>;console.log(created.id, created.state);

   GoCopy

   created, err := kl.Workspaces.Restore(kloudlite.RestoreWorkspace{    Snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d",    To:       "api-restored",    Packages: []string{"ripgrep", "nodejs@20"},    QuotaGb:  40,})if err != nil {    log.Fatal(err)}fmt.Println(created["id"], created["state"])

   RubyCopy

   created = kl.workspaces.restore(snapshot: "ws-0a1b2c3d4e5f6a7b-8a7b6c5d", to: "api-restored", packages: ["ripgrep", "nodejs@20"])puts created.values_at("id", "state").join(" ")

   JavaCopy

   String created = kl.workspaces().restore(new Kloudlite.RestoreWorkspace()    .snapshot("ws-0a1b2c3d4e5f6a7b-8a7b6c5d")    .to("api-restored")    .packages("ripgrep", "nodejs@20")    );System.out.println(created);

   CLICopy

   kode workspaces restore --snapshot ws-0a1b2c3d4e5f6a7b-8a7b6c5d --to api-restored --package ripgrep --package nodejs@20

Close-out

1. Wait until the state of the new workspace is ready.
2. Examine packages_status. Make sure that the packages are installed.

Troubleshooting