Creating and listing

You create a Workspace from a Template with the Go SDK, the E2B SDK, or kibo workspace create, choosing its resources, network access, and Volume as you go. This page covers choosing a Template, the parameters of create, and finding Workspaces again in lists.

Listing TemplatesCopy Anchor Link

Every WorkspaceA complete Linux environment for an AI Agent, running in its own MicroVM. Agents read and write files, run processes, and start services in it without affecting the host or other Workspaces. is created from a TemplateThe system image a Workspace is created from, such as a minimal system, a programming toolchain, or a desktop environment.. List the Templates you can use, then look at one of them:

kibo template list
kibo template get "$template_id"

• template list shows only selectable Templates by default. --selection any lists all of them.
• template get shows the Template's default revision. Pass --revision to see an exact revision.
• Both commands only read the catalog. Publishing and approving Templates is done by an Operator; see Catalog and Build your own Template.

Creating a WorkspaceCopy Anchor Link

Create a Workspace from a Template and keep its ID. The Go example uses the client from Connect to ctrl:

commandID := kibotos.NewCommandID("example")
created, err := client.Workspaces().CreateWorkspace(ctx, connect.NewRequest(&ctrlv1.CreateWorkspaceRequest{
	Metadata: &ctrlv1.CommandMetadata{CommandId: commandID},
	Spec: &ctrlv1.WorkspaceCreateSpec{
		Template:  &ctrlv1.TemplateSelector{TemplateId: templateID},
		Resources: &ctrlv1.ResourceRequest{CpuMillis: 1000, MemoryBytes: 256 << 20},
	},
}))
if err != nil {
	log.Fatal(err)
}
workspace, err := client.WaitWorkspace(ctx, created.Msg.GetWorkspace(), commandID)
if err != nil {
	log.Fatal(err)
}
workspaceID := workspace.GetWorkspaceId()

• In the Go SDK and the native API, Template and Resources are required. The request returns as soon as ctrl accepts it, and WaitWorkspace waits until the Workspace is available.
• The E2B gateway sets the resources from its deployment settings. See Resources.

The rest of this section describes kibo. Each flag has a field in the request; see With the API.

With no other flags, the Workspace gets 1 CPU, 256 MiB of memory, no network access, and a new Volume mounted at /data. By default kibo waits until the Workspace is available. With --no-wait, it returns as soon as ctrl accepts the request, and the Workspace may still be CREATING. See Waiting for results.

Create a Workspace with more resources:

kibo workspace create --template "$template_id" --cpu 2 --memory 4G --disk 20G

Every flag of create, with its default, is listed under kibo workspace create. Sizes are binary: 4G means 4 GiB, and GB or MB are rejected. See Size and CPU formats.

Template and resourcesCopy Anchor Link

• Without --template-revision, the Workspace uses the Template's current default revision, which is then pinned to the Workspace.
• The instance gets exactly the memory requested with --memory. It must be a whole number of MiB and at least 128 MiB.
• Without --disk, the node's storage configuration decides the capacity of the writable layer. --disk must be a whole number of MiB, and the node also uses this value for disk capacity admission.
• The node reserves 1 MiB of --disk for the next start after the writable layer fills up, so the free space seen in the guest is 1 MiB less.

Network accessCopy Anchor Link

A new Workspace has no network access. To open it, pass --network public-internet, optionally with destination rules:

kibo workspace create --template "$template_id" --network public-internet --deny 0.0.0.0/0 --allow 203.0.113.0/24

The other network flags work only with --network public-internet:

• --allow and --deny add destination rules. See Network policy.
• --egress and --egress-destination send TCP to these destinations out via the caller's Egress. See Routing connections through an Egress.
• --resolver and --resolver-path forward the guest's DNS queries to the caller's Resolver. See Referencing a Resolver in the policy.

VolumeCopy Anchor Link

By default each Workspace gets a new Volume mounted at /data. To bind an existing Volume, change the mount path, or create the Workspace without a Volume, see Volumes at creation.

Expiration, labels, and annotationsCopy Anchor Link

• --expires-in and --expiration-action set when the Workspace expires and whether it is then stopped or deleted. See Expiration.
• --label and --annotation attach the caller's own key-value data. See Labels and annotations.

Filtering listsCopy Anchor Link

kibo workspace list and kibo volume list hide deleted resources by default. Combine filters to narrow the list:

kibo workspace list --state AVAILABLE --label team=infra
kibo volume list --include-deleted

• --include-deleted also shows deleted resources. With the API, ListWorkspaces and ListVolumes return DELETED objects only when include_deleted is true.
• --state and --guest-unresponsive filter only Workspaces. For when a guest counts as unresponsive, see Responsiveness of the guest.
• For label filters, see Filtering by label.
• Every filter is listed under kibo workspace list and kibo volume list.

PagesCopy Anchor Link

Both lists fetch one page at a time. The server decides the page size, and --page-size can set it to at most 100.

• When there is a next page, the summary states that this is only one page and gives the command for the next page below it.
• --all reads all results page by page. It cannot be combined with --page-token.
• Reading page by page is not a snapshot of one moment. Resources created or deleted in the meantime may or may not appear.
• When -q prints only the IDs of one page, stderr notes that there is a next page.

To get every Workspace ID in a script, combine -q with --all:

kibo workspace list -q --all

With the APICopy Anchor Link

• kibo workspace create maps to WorkspaceService/CreateWorkspace. Template, resources, Volume, and network policy go in the request's spec (WorkspaceCreateSpec), for example --cpu as resources.cpu_millis; expiration, labels, and annotations are fields of CreateWorkspaceRequest itself. The request returns as soon as it is accepted, with the Workspace in CREATING.
• kibo template list and kibo template get map to ListTemplates, GetTemplate, and GetTemplateRevision of TemplateService.

Next stepsCopy Anchor Link

• Choosing an environment: get the software your Agent needs into a Workspace.
• Commands and terminals: run commands in the new Workspace.
• Networking overview: open access to the internet and control destinations.
• Volumes, export, and restore: bind existing Volumes and keep data.
• Labels and annotations: tag Workspaces and find them by label.