Architecture

Kibotos handles your requests in two places: ctrlThe control-plane service of a Kibotos cluster. It accepts control-plane requests, decides which host each Workspace runs on, and issues session credentials for the data plane. manages Workspaces, and the nodeThe service that runs on every host. It starts and stops the MicroVMs of Workspaces and serves the data plane. that runs a Workspace serves its files, processes, and terminals. This page shows which components each request passes through, and how that affects the way you call Kibotos. To deploy and operate Kibotos, see Installation.

ComponentsCopy Anchor Link

flowchart LR
  K["Your program<br/>kibo / native API"]
  C["ctrl<br/>control plane"]
  N["node<br/>data plane"]
  G["guest agent<br/>inside the MicroVM"]

  K -->|Manage Workspaces<br/>request credentials| C
  K -->|Files, processes, terminals| N
  C -->|Placement, start and stop| N
  N -->|vsock| G

When you use kibo or the native API, your requests pass through no gateway. When you use the E2B SDK, the E2B gateway takes the place of "Your program" in the diagram: it calls ctrl, requests credentials, and connects to the node for you. Public URL traffic goes through the Exposure gateway to the node, and for each request the gateway obtains from ctrl a credential that is valid for that request only.

How a request flowsCopy Anchor Link

Creating a Workspace:

1. You send a create request to ctrl, which accepts it and returns immediately. The Workspace is in CREATING.
2. It then picks a host that has enough resources and can reach the required storage pools. If needed, it first prepares the Template on that host.
3. The node on that host starts the MicroVM. Once the guest agent is ready, the Workspace becomes AVAILABLE.

By default, kibo workspace create waits for this step to finish. With the native API, poll the Workspace state or query the result of the create command.

Running a command in a Workspace:

1. You request a data-plane credential from ctrl. The response includes the address of the node that runs the Workspace.
2. You connect directly to that node with the credential and ask it to start a process.
3. The node hands the request to the guest agent over the vsock channel between the host and the MicroVM. Output returns the same way.

Steps 2 and 3 do not pass through ctrl.

What this means for callersCopy Anchor Link

• Request a credential before you access the data plane. Credentials are short-lived. When one expires, request a new one. Both kibo and the E2B gateway request and renew credentials automatically.
• Old connections stop working after a restart. Every start is a new generation. All credentials, processes, and connections of the previous generation become invalid, so you need to request a new credential and start your processes again. This is also why processes and memory are not kept across a stop and start.
• Connections drop when a host fails. In-flight file transfers and process connections are cut off. After the deployer confirms that the host has failed, its Workspaces become FAILED. You can then start them again, and Kibotos places them on another host that can reach their storage. For the data retention rules, see Guarantees and limits.
• The data-plane address can change. Each start can land on a different host. Do not cache the node address; always use the one in the credential response.

Two MicroVM backendsCopy Anchor Link

The deployer can run MicroVMs with Firecracker or KiboVM. Both provide the same API and are mostly transparent to callers. They differ only when the guest reboots or shuts itself down:

To stop or restart a Workspace, use the Kibotos stop and start interfaces instead of shutting down or rebooting from inside the guest. For details, see Stops and restarts handled by the server.

Next stepsCopy Anchor Link

• Guarantees and limits: which data is kept under which conditions, the limits of networking and isolation, and what you see when something goes wrong.
• API overview: the addresses, authentication, and protocol details of the two endpoints.