Sandboxes

Description and operation

General

A sandbox is a short-lived, isolated machine for one run of code that you wrote. It has a file system, a toolchain and a network. It has no effect on other workspaces.

A sandbox runs one main process. You give the command at creation. The sandbox ends when that process exits. Other processes can run inside the sandbox, but the sandbox waits only for the main one.

A sandbox runs once. When it ends, its files are gone and it cannot start again. To run again, create a new sandbox.

Each sandbox has its own kernel, file system and network stack, with allocated vCPU, memory and disk. A sandbox belongs to you or to a team that you are an active member of. Nobody else sees it. The platform gives it an id that starts with sbx-.

Sandbox types

A sandbox is standalone or in a session. The type is set at creation and does not change.

Sources

A sandbox starts from one of three sources. The source decides what is in the sandbox when it starts.

Creation parameters

The variables belong to the main process. A variable name uses letters, digits and _, does not start with a digit, and is not HOME or KL_ followed by anything.

States

A sandbox never stops and starts again. A create call returns at once with the phase pending. A fast command can end without the sandbox being running.

The record also has exit_code, message (the cause of a failure), the times, the size and the source.

Lifecycle

• Create. The call returns at once. The phase is pending, then starting, then running.
• Run. The hard lifetime counts from running and always applies. A sandbox has no idle limit.
• In a session. A sandbox created through a session is controlled through that session. It ends when the session ends. See Sandboxes.
• End. The main process exits, you end the sandbox, or the time limit ends it. Its processes end and its files are gone.
• Record. The record of an ended sandbox stays for 90 days. It shows the phase, the reason, the exit code, the output, the times, the size and the source. A delete removes the record.

Quota and limits

A running sandbox counts its CPU, memory and disk against the owner's quota. An ended sandbox counts nothing. The sandboxes dimension of the quota limits how many sandboxes run at the same time.

Tasks

Create a sandbox with a command

Reason for the task: Start an isolated machine that runs one command and ends with it.

Job set-up

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

Procedure

1. Create the sandbox with the command. The call returns at once.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()sb = kl.sandboxes.create(cmd=["python3", "main.py"], packages=["python3"], timeout_s=600)

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();const sb = await kl.sandboxes.create({ cmd: ["python3", "main.py"], packages: ["python3"], timeoutS: 600 });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})sb, err := kl.Sandboxes.Create(kloudlite.CreateSandbox{Cmd: []string{"python3", "main.py"}, Packages: []string{"python3"}, Timeout: 600 * time.Second})if err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newsb = kl.sandboxes.create(cmd: ["python3", "main.py"], packages: ["python3"], timeout_s: 600)

   JavaCopy

   var kl = new Kloudlite();var sb = kl.sandboxes().create(new Kloudlite.CreateSandbox().cmd(List.of("python3", "main.py")).packages("python3").timeout(Duration.ofSeconds(600)));

   CLICopy

   kloudlite sandboxes create --package python3 --timeout-s 600 -- python3 main.py

Close-out

1. Show the status as in task 002. Make sure that phase is pending, starting, running or terminated.

Show the status of a sandbox

Reason for the task: Read the phase of a sandbox and, when it ended, the reason and the exit code.

Job set-up

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

Procedure

1. Read the record of the sandbox. The record shows the phase, the reason, the exit code and the times.

   PythonCopy

   print(kl.sandboxes.get(sandbox="sbx-3c4d5e6f7a8b9c0d").doc)

   TypeScriptCopy

   console.log((await kl.sandboxes.get({ sandbox: "sbx-3c4d5e6f7a8b9c0d" })).doc);

   GoCopy

   got, err := kl.Sandboxes.Get("sbx-3c4d5e6f7a8b9c0d")if err != nil {    log.Fatal(err)}fmt.Printf("%+v\n", got.SandboxDoc)

   RubyCopy

   pp kl.sandboxes.get(sandbox: "sbx-3c4d5e6f7a8b9c0d").doc

   JavaCopy

   System.out.println(kl.sandboxes().get("sbx-3c4d5e6f7a8b9c0d").json());

   CLICopy

   kloudlite sandboxes get sbx-3c4d5e6f7a8b9c0d

2. Wait until the sandbox is running. The call fails with the reason when the sandbox ends first.

   PythonCopy

   sb.wait_running(timeout_s=120)

   TypeScriptCopy

   await sb.waitRunning({ timeoutS: 120 });

   GoCopy

   if err := sb.WaitRunning(120 * time.Second); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.wait_running(timeout_s: 120)

   JavaCopy

   sb.waitRunning(Duration.ofSeconds(120));

   CLICopy

   kloudlite sandboxes wait-running sbx-3c4d5e6f7a8b9c0d --timeout-s 120

Close-out

1. Make sure that the phase is running, or terminated with a reason. Make sure that exit_code is set when the reason is Exited.

End a sandbox

Reason for the task: Stop a sandbox before its command exits or its time limit, and release its resources.

Job set-up

• Access: you.
• Conditions: you have the handle sb. Use sandboxes.get with the id to get it.
• References: POST /v1/sandboxes/{id}/terminate, DELETE /v1/sandboxes/{id}.

Procedure

1. Stop the sandbox. The call is safe to repeat.

   PythonCopy

   sb.terminate()

   TypeScriptCopy

   await sb.terminate();

   GoCopy

   if err := sb.Terminate(); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.terminate

   JavaCopy

   sb.terminate();

   CLICopy

   kloudlite sandboxes terminate sbx-3c4d5e6f7a8b9c0d

2. Wait until the sandbox ends. The call returns the exit code, or no code when the process did not exit by itself.

   PythonCopy

   code = sb.wait()

   TypeScriptCopy

   const code = await sb.wait();

   GoCopy

   code, err := sb.Wait(0)if err != nil {    log.Fatal(err)}

   RubyCopy

   code = sb.wait

   JavaCopy

   int code = sb.waitFor(null);

   CLICopy

   kloudlite sandboxes wait sbx-3c4d5e6f7a8b9c0d

3. Delete the record if you do not need it.

   PythonCopy

   sb.delete()

   TypeScriptCopy

   await sb.delete();

   GoCopy

   if err := sb.Delete(); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.delete

   JavaCopy

   sb.delete();

   CLICopy

   kloudlite sandboxes delete sbx-3c4d5e6f7a8b9c0d

Close-out

1. Make sure that reason is Terminated, or Exited when the command ended first.

Show the run records

Reason for the task: Find the sandboxes of an owner and read why each one ended.

Job set-up

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

Procedure

1. Show the sandboxes, newest first. Give a team to show only its sandboxes.

   PythonCopy

   for s in kl.sandboxes.list():    print(s.id, s.phase, s.reason)

   TypeScriptCopy

   for (const s of await kl.sandboxes.list()) {  console.log(s.id, s.phase, s.reason);}

   GoCopy

   sandboxes, err := kl.Sandboxes.List("")if err != nil {    log.Fatal(err)}for _, s := range sandboxes {    fmt.Println(s.ID, s.Phase, s.Reason)}

   RubyCopy

   kl.sandboxes.list.each do |s|  puts "#{s.id} #{s.phase} #{s.reason}"end

   JavaCopy

   for (var s : kl.sandboxes().list(null)) {    System.out.println(s.id() + " " + s.phase() + " " + s.reason());}

   CLICopy

   kloudlite sandboxes list

Close-out

1. Make sure that each ended sandbox shows the phase terminated, a reason and its times.

Read the output and the exit code

Reason for the task: Read what the command printed and how it ended.

Job set-up

• Access: you.
• Conditions: you have the handle sb. Use sandboxes.get with the id to get it.
• References: GET /v1/sandboxes/{id}/logs, POST /v1/sandboxes/{id}/wait.

Procedure

1. Wait for the command to exit. The call returns the exit code.

   PythonCopy

   code = sb.wait()

   TypeScriptCopy

   const code = await sb.wait();

   GoCopy

   code, err := sb.Wait(0)if err != nil {    log.Fatal(err)}

   RubyCopy

   code = sb.wait

   JavaCopy

   int code = sb.waitFor(null);

   CLICopy

   kloudlite sandboxes wait sbx-3c4d5e6f7a8b9c0d

2. Read the output. Give follow to hold the call until the command ends.

   PythonCopy

   print(sb.logs())

   TypeScriptCopy

   console.log(await sb.logs());

   GoCopy

   out, err := sb.Logs(false)if err != nil {    log.Fatal(err)}fmt.Print(out)

   RubyCopy

   puts sb.logs

   JavaCopy

   System.out.print(sb.logs(false));

   CLICopy

   kloudlite sandboxes logs sbx-3c4d5e6f7a8b9c0d

Close-out

1. Make sure that the exit code is 0 and the output is the one that you expect.

Troubleshooting