Guarantees and limits

Kibotos makes explicit guarantees about when your data is kept, the limits of networking and isolation, what you see when something goes wrong, and which interfaces carry compatibility commitments.

DataCopy Anchor Link

Data in a Workspace falls into three categories, each with its own retention rules:

Write data that must be kept reliably to the Volume mount directory.

• A Volume is deleted only when you delete it, or when you delete its Workspace and the binding settings say to delete it. A Volume that you unbind or rebind elsewhere is not deleted. Its data stays intact, and you can bind it to another Workspace.
• The writable layerThe writable part of a Workspace's root file system, holding changes such as installed packages; Operator pages call it the retained layer. It is kept on a best-effort basis, and only the Volume is guaranteed to keep data. holds the changes you make on the root file system, such as installed packages. After a normal stop and start, it is used again. If its storage is damaged or lost, the Workspace starts with a fresh writable layer, and the Workspace information reports the reset and its reason. Do not treat it as your only copy.
• /tmp and /run are empty at every start. Memory and processes are not kept across starts, and the same applies to E2B pause and resume: after a resume, files are kept as in the table above, and processes need to be started again.
• If a host fails suddenly, data written in the last few seconds that has not yet reached storage may be lost, as when an ordinary computer loses power.
• From v0.3.0, when the deployer declares a storage pool lost, the Volumes in it become LOST, and Workspaces bound to them cannot start. Writable layers are reset.

Export and restore: An export contains only the files in the Volume. It does not contain the writable layer, memory, or processes, and the .kibotos/credentials and .kibotos/browser-state directories are not exported either. Restoring produces a new Workspace. You need to supply its ID, labels, and annotations again, and sessions and sign-in state need to be re-established. By default, an archive is kept for 24 hours and is at most 1 GiB; the deployer configures both values. See Export, import, and restore and Archive retention.

Workspaces and TemplatesCopy Anchor Link

• A Workspace's Template revision is fixed when the Workspace is created and does not change afterward. When the deployer publishes a new version or changes the default revision, only newly created Workspaces are affected.
• After the deployer withdraws a revision, you can no longer create Workspaces from it, but Workspaces that already use it start as usual.
• At start, the deployer may give a Workspace a newer kernel and runtime environment from the same series to apply security fixes. The content of the Template itself does not change.

NetworkingCopy Anchor Link

• No network access by default. A new Workspace has no outbound access at all, and its DNS queries are refused. To give it network access, change the network policy at creation or later. See Network policy.
  • Exception: when you create a Workspace with the E2B SDK, the SDK requests public internet access by default. See E2B compatibility.
• Once public internet access is open, the Workspace can open TCP connections, send pings, and make DNS queries. Other UDP traffic, such as QUIC and NTP, is not allowed.
• You can fine-tune by destination address: list the addresses to allow and to deny as IP addresses or CIDRs, up to 256 entries in total across both lists. Configuration by domain name is not supported.
• Always unreachable, regardless of the network policy:
  • Private addresses, carrier-grade NAT addresses, loopback and link-local addresses (including the metadata address 169.254.169.254 common on cloud platforms), and multicast and reserved addresses, for both IPv4 and IPv6;
  • The host itself and the deployer's management network;
  • Other Workspaces.
• Except through a caller-owned egress: TCP connections that leave through an Egress you configure go wherever your proxy sends them, which can include your own internal network. Egress requires v0.3.0 or later.
• Inbound: Nothing outside can connect directly to a Workspace. To reach a service in a Workspace from outside, use port forwarding, a service connection, or a public URL.
• Outbound traffic from all Workspaces leaves from the host's public address. If you need a fixed egress address, use an Egress.

IsolationCopy Anchor Link

• Each Workspace runs in its own MicroVM with its own kernel, file system, and network. Processes in one Workspace cannot see or access another Workspace.
• You can run processes as root in a Workspace. Root privileges apply only inside that MicroVM.
• Workspaces on the same host share the host's CPU, memory, and disk bandwidth. Resource limits are enforced according to the CPU and memory set at creation or adjustment.

Credentials and accessCopy Anchor Link

• Credentials for accessing the data plane are short-lived (5 minutes by default, 15 minutes at most; at most 1 hour for a credential bound to an execution) and are valid only for the current generation of one Workspace.
• When a Workspace stops or is deleted, all credentials already issued become invalid and open connections are closed.
• To cut off all existing access immediately without stopping the Workspace, revoke its data-plane access. See RevokeWorkspaceDataPlane in the native API.
• The kibo command holds credentials only while it runs and never writes them to disk.
• A public URL needs no credential. Anyone who has the address can access it, so revoke it when you are done.

Accurate result reportingCopy Anchor Link

• Incomplete work is never reported as success. A write operation either completes or returns a failure or "still in progress". It never returns success when only part of it has completed.
• Failures come with reasons. Besides the standard error code, an error carries a reason, the stage where it happened, and whether it can be retried. For example, when resources run out, the request returns resource_exhausted marked as retryable.
• Uncertain results are reported as uncertain. When a host is temporarily unreachable, a Workspace may be in UNKNOWN, and related commands stay "in progress". Resend with the original command ID or query the command until you get a definite result. Do not resubmit with a new command ID.
• Cleanup progress after deletion is queryable. After a deletion, you can check item by item whether the runtime environment, Volume, writable layer, and other parts have been released. See Checking cleanup status.

Compatibility commitmentsCopy Anchor Link

The commitment covers the interfaces that external applications call directly. It starts at v0.1.0; the earlier v0.0.x releases are pre-releases with no compatibility commitment.

Breaking changes come with a transition period of one MINOR release.

• A replaced field or method keeps working in the release that introduces the new form, and is marked deprecated.
• The old form is removed in the next MINOR release at the earliest. When vX.Y.0 introduces a replacement, the old form disappears in vX.(Y+1).0 at the earliest.
• PATCH releases remove nothing.

A new form is announced with a new capability name. During the transition period, both the old and the new name appear in the capability list from GetServerInfo. To tell which form a server provides, match capability names exactly and fail only the operation whose name is missing, as described in Querying capabilities first. Do not branch on source_revision or version numbers.

Every breaking change is described in advance in the release notes. The upgrade notes section (升级须知) of each release in CHANGELOG.md says what changed, in which release the old form is removed, what callers must do, and how to tell whether you are affected. Reading this section before an upgrade is enough. The body of the GitHub Release is the same text.

Outside the commitment:

• The flags and output of kibo, the deployment configuration format, the database schema, release artifact naming, and the internal interface between node and guest. They are replaced together with the whole installation, and continuity is handled by Reinstall and upgrade.
• The Go API of the Go SDK, including its generated code. It follows its own rule instead: until v1, it changes only in MINOR releases. See Go SDK compatibility.

Not currently providedCopy Anchor Link

• Saving or restoring memory state.
• Taking a snapshot of a Workspace, creating a Workspace from a snapshot, or making a copy of it (fork).
• Moving a running Workspace between hosts without interruption.
• Network policies configured by domain name.