Core concepts
Templates, Workspaces, and Volumes are the objects you work with every time you use Kibotos. This page introduces them and the other objects, the states of a Workspace, and the two access paths: the control plane and the data plane.
Objects
flowchart LR T["Template<br/>revision"] -->|fixed at creation| W[Workspace] W ---|binds 0 or 1| V[Volume] W -.->|referenced by network policy| E[Egress] W -.->|referenced by network policy| R[Resolver] X[Exposure] -->|exposes one port| W W -->|export| TR[Transfer] TR -->|restore as new| W2[Workspace]
Templates and revisions
A Template is the system image used to create Workspaces, such as a minimal system, a programming toolchain, or a desktop environment.
- Every publish produces an immutable revision. The deployer selects a default revision for each Template.
- When you create a Workspace, you can name only the Template and let the system pick the current default revision, or you can name a specific revision.
- Once chosen, the revision never changes. If the deployer later publishes a new version or changes the default revision, existing Workspaces keep the revision they have.
Workspaces
A Workspace is the environment an Agent works in. Each Workspace runs in its own MicroVM.
- Its ID never changes after creation.
- Every successful start is a new run, called a generation, numbered from 1 upward. After a stop, all credentials, processes, and connections of that run become invalid, and you need to request new credentials after the next start.
- Its attributes are CPU, memory, writable layer size, expiration time, network policy, labels, and annotations. The writable layer is the writable part of the root file system. For its retention rules, see Guarantees and limits.
- Volumes and writable layers are stored in the deployer's storage pools. At every start, the system picks a host that can reach these storage pools to run the Workspace. It may not be the same host as last time.
Volumes
A Volume is a persistent volume that exists independently of any Workspace.
- By default, creating a Workspace also creates a dedicated Volume mounted at
/data. You can instead bind an existing Volume, or have no Volume at all. - A Workspace binds at most one Volume, and a Volume belongs to only one Workspace at a time. After a Workspace stops, you can rebind or unbind its Volume. The change takes effect at the next start.
- A Volume created by default is deleted together with its Workspace, and a bound existing Volume is kept by default. You can change either behavior when you bind the Volume. For when data is kept, see Guarantees and limits.
Other objects
| Object | What it is | Details |
|---|---|---|
| Exposure | Turns an HTTP port in a Workspace into a public https:// address | Public URLs |
| Egress | An outbound proxy provided by the caller. When the network policy references it, outbound connections go through it. Requires v0.3.0 or later | Egress |
| Resolver | A DNS server provided by the caller. When the network policy references it, DNS queries go through it. Requires v0.3.0 or later | Resolvers chosen by the caller |
| Transfer | Exports the Volume of a stopped Workspace to an archive, which you can then import as a new Volume and restore as a new Workspace with a different ID | Export, import, and restore |
| labels and annotations | Key-value pairs attached to objects such as Workspaces and Volumes. You can filter lists by labels; annotations are only stored | Labels and annotations |
Workspace states
stateDiagram-v2 CREATING --> AVAILABLE AVAILABLE --> STOPPING: stop / expire STOPPING --> STOPPED STOPPED --> STARTING: start STARTING --> AVAILABLE AVAILABLE --> FAILED: error FAILED --> STOPPED: force stop STOPPED --> DELETING: delete DELETING --> DELETED
| State | Meaning |
|---|---|
CREATING | Choosing a host, preparing the Template, and starting the MicroVM |
AVAILABLE | Running; files and processes are accessible |
STOPPING | Stopping |
STOPPED | Stopped; uses no CPU or memory |
STARTING | Starting |
FAILED | Something went wrong during creation, start, or while running |
UNKNOWN | The result of an operation cannot be confirmed for the moment |
DELETING | Deleting |
DELETED | Deleted; still queryable by ID |
The diagram shows only the main paths:
- You can delete a Workspace directly from any state except
DELETINGandDELETED. - Errors during creation and start also lead to
FAILED. - Whether the guest is responding (
RESPONDINGorUNRESPONSIVE) is reported separately and does not change the state.
For the operations allowed in each state and how to recover from FAILED, see Operations by state and Recovering from FAILED.
Control plane and data plane
There are two paths into Kibotos:
| Control plane | Data plane | |
|---|---|---|
| What it does | Create, query, stop, and delete Workspaces; manage objects such as Volumes and Exposures | Read and write files, run processes, open terminals and desktops |
| Where requests go | ctrl | The host that runs the Workspace |
| How you authenticate | An Operator identity issued by the deployer, with mutual TLS | A short-lived session credential requested from ctrl first |
File and process traffic does not pass through ctrl, so large files and long-running output are unaffected by load on the control plane. The cost is one extra step to request a credential, and another request after each Workspace restart. Both kibo and the E2B gateway do this for you. For how requests flow, see Architecture.
Write operation conventions
| Convention | What to do |
|---|---|
| Command ID | Every write request carries a command ID generated by the caller. Resending with the same command ID does not run the operation twice; if the result is already available, you get it directly |
| Expected revision | When you modify an existing object, include the revision you read. If someone else modified it first, the request is rejected instead of silently overwriting their change |
| Unknown result | When a request times out or the connection drops, resend it with the original command ID, or query the result of that command. A different command ID makes it a new operation |
For the exact fields and error codes, see Write operation conventions on the native API page.
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.
Architecture
Kibotos handles your requests in two places: ctrl manages Workspaces, and the node 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.