Quickstart

Create your first Workspace, run commands and transfer files in it, and delete it, all in a few minutes. You need a running Kibotos deployment; if there is none yet, install one yourself by following Try Kibotos on a single machine.

Choose one of three paths:

• Using kibo: the command line, for trying things by hand and writing scripts.
• Using the E2B SDK: for programs already using the E2B SDK, which switch over by changing only the connection settings.
• Using the Go SDK: for Go programs that manage Workspaces themselves.

Using kiboCopy Anchor Link

PrerequisitesCopy Anchor Link

Ask the deployer for these three things:

1. Install and enrollCopy Anchor Link

Install kibo, exchange the enrollment key for your Operator identity, and then delete the used key:

sudo install -m 0755 kibo_1.2.3_linux_amd64 /usr/local/bin/kibo
umask 077
kibo context enroll --endpoint https://ctrl.example.com:18092 --key-file operator-enrollment.key
rm operator-enrollment.key

The identity is stored in the context directory on your machine, ~/.config/kibo/context by default. All later commands use it automatically, with no further key or password to enter.

Confirm that you can reach ctrl. The output should include Compatible yes:

kibo version

2. Choose a TemplateCopy Anchor Link

The TemplateThe system image a Workspace is created from, such as a minimal system, a programming toolchain, or a desktop environment. determines what comes preinstalled in the Workspace. List the Templates the deployer provides:

kibo template list

TEMPLATE         DEFAULT REVISION     SELECTION   DELIVERY
kibotos-minimal  sha256:8cb0f385e54a  SELECTABLE  READY

The first column is the Template ID. This page uses kibotos-minimal; the name may differ in your deployment.

3. Create a WorkspaceCopy Anchor Link

Create a Workspace and store its ID in a variable:

workspace_id=$(kibo workspace create --template kibotos-minimal -q)
echo "$workspace_id"

• The command returns once the Workspace is ready to use, usually within a few seconds.
• Without -q, it prints a summary that includes CPU, memory, Volume, and network settings.
• The defaults are 1 CPU, 256 MiB of memory, no network access, and one Volume mounted at /data. For the parameters, see Creating a Workspace.

4. Run a commandCopy Anchor Link

Run a command in the Workspace. Its output prints directly on your machine:

kibo workspace exec "$workspace_id" -- uname -sr
kibo workspace exec "$workspace_id" -- sh -c 'echo "hello from $(hostname)"'

The exit code of kibo is the exit code of the remote command, so you can use it directly in script conditions. When kibo itself fails, for example because the Workspace is not found, it exits with 255. A command stopped by --exec-timeout exits with 124. See kibo exit codes.

5. Upload and download filesCopy Anchor Link

Upload a local file, process it in the Workspace, and fetch the result:

printf 'hello kibotos\n' > notes.txt
kibo workspace file put "$workspace_id" notes.txt /data/notes.txt
kibo workspace exec "$workspace_id" -- sh -c 'wc -c /data/notes.txt > /data/result.txt'
kibo workspace file get "$workspace_id" /data/result.txt result.txt
cat result.txt

/data is the VolumeA persistent volume that exists independently of any Workspace. A Workspace binds at most one Volume, mounted at /data by default., so its data survives a stop and start of the Workspace. For the retention rules of other paths, see Guarantees and limits.

6. Open a terminalCopy Anchor Link

Open an interactive shell. Type exit to leave it:

kibo workspace terminal "$workspace_id"

7. Access the networkCopy Anchor Link

A new Workspace has no network access by default. Allow it to reach the public internet; the change takes effect immediately:

kibo workspace network set "$workspace_id" public-internet
kibo workspace exec "$workspace_id" -- curl -sS -o /dev/null -w '%{http_code}\n' https://example.com

To allow only some addresses, or to send traffic out through your own proxy (v0.3.0 or later), see Networking overview.

8. Delete the WorkspaceCopy Anchor Link

Delete the Workspace, and type y at the confirmation prompt. The Volume created with it is deleted too:

kibo workspace delete "$workspace_id"

To delete from a script, add --yes to skip the confirmation.

Using the E2B SDKCopy Anchor Link

PrerequisitesCopy Anchor Link

• Node.js 22 or later.
• Ask the deployer for the E2B gateway's API key, its domain (for example, sandbox.example), and the names of the available Templates.
• If the gateway certificate is issued by a private CA, you also need that CA's certificate file.

1. Install the SDKCopy Anchor Link

Install the E2B JavaScript SDK in a new directory. Kibotos acceptance tests use version 2.46.1:

npm init -y
npm install e2b@2.46.1

2. Write the programCopy Anchor Link

Save the following as quickstart.mjs. It creates a sandbox, runs commands, writes and reads a file, and finally deletes the sandbox:

import { Sandbox } from 'e2b';

const sandbox = await Sandbox.create('kibotos-minimal');
try {
  const result = await sandbox.commands.run('uname -sr');
  console.log(result.stdout);

  await sandbox.files.write('/tmp/notes.txt', 'hello kibotos\n');
  await sandbox.commands.run('wc -c /tmp/notes.txt > /tmp/result.txt');
  console.log(await sandbox.files.read('/tmp/result.txt'));
} finally {
  await sandbox.kill();
}

In Kibotos, an E2B sandbox is a Workspace. Replace kibotos-minimal with the Template name the deployer gave you.

3. Run itCopy Anchor Link

The SDK reads the API key and domain from environment variables. The following assumes the API key is stored in the file e2b-api-key.txt. Set the environment variables and run the program:

export E2B_API_KEY="$(cat e2b-api-key.txt)"
export E2B_DOMAIN=sandbox.example
node quickstart.mjs

If the gateway certificate is issued by a private CA, make Node.js trust that CA before you run the program, for example with export NODE_EXTRA_CA_CERTS="$PWD/sandbox-ca.pem".

Using the Go SDKCopy Anchor Link

PrerequisitesCopy Anchor Link

• Go 1.27 or later, and a checkout of the Kibotos repository. While the repository is not public, you need read access to it.
• The ctrl address and the name of a Template.
• An enrollment key for your program. An Operator creates it with kibo enrollment create --operator my-program --output my-program.key.

1. Run the exampleCopy Anchor Link

examples/go/quickstart connects to ctrl, creates a Workspace, runs a command, transfers a file, and deletes the Workspace. Its first run exchanges the key for an identity and stores it in the directory you name:

go run ./examples/go/quickstart -endpoint https://ctrl.example.com:18092 \
  -identity "$HOME/.local/state/kibotos-quickstart" -enrollment-key-file my-program.key

Later runs reuse the directory and need no key. Add -template when the deployment has no kibotos-minimal.

2. Use it as your starting pointCopy Anchor Link

The example imports only the SDK module. To use the SDK in your own module, see Go SDK.

NotesCopy Anchor Link

• The E2B gateway covers the basic E2B capabilities and returns an explicit error for anything it does not provide. See Not supported. If the deployment is older than v0.3.0, use absolute file paths.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link

• Core concepts: Workspaces, Templates, Volumes, and states.
• kibo CLI: the remaining commands, plus waiting, command IDs, and result queries.
• Lifecycle: what is kept after a stop and how to recover when something goes wrong.
• API overview: for programs that need the full feature set and compatibility commitments.
• Agent platform integration: connect an Agent platform to Kibotos.
• E2B compatibility: the endpoints the gateway supports and how its behavior differs.