Agent platform integration

This page shows how to connect an Agent platform to Kibotos: where the Operator identity lives, how Agent sessions map to Workspaces and Volumes, and how the platform handles failures. The code uses the Go SDK. Programs in other languages make the same calls through the native API.

OverviewCopy Anchor Link

Your platform backend sits between the Agent and Kibotos. It manages Workspaces through ctrl and reaches the node that runs each Workspace with a short-lived credential:

flowchart LR
  Agent[Agent runtime] -->|tool calls| Backend[Platform backend]
  Backend -->|mTLS with the Operator identity| Ctrl[ctrl]
  Backend -->|session credential| Node[node data plane]
  Node --> Workspace[Workspace]

A typical session runs in this order:

1. Find or create the project's Volume.
2. Create a Workspace bound to that Volume, with an expiration time.
3. Run the Agent's tool calls through a data-plane session.
4. Delete the Workspace when the session ends. The Volume stays for the next session.

Coding Agent with a persistent project is a complete program that follows these steps.

Identity and accessCopy Anchor Link

• Your platform authorizes its own users. Kibotos has no tenants. Every Operator sees every Workspace, so your backend decides which user may reach which Workspace.
• Labels are not access control. Use them to find resources. See Labels and annotations.
• Each backend instance needs its own identity directory. ctrl accepts only the current and the previous certificate of an identity, so two programs renewing one identity lock each other out. Create one enrollment key per instance with kibo enrollment create --operator. See Connect to ctrl.

Agent access to a WorkspaceCopy Anchor Link

Choose how the Agent's tool calls reach the Workspace:

To hand out a credential, request only the scopes the Agent needs and a short lifetime:

response, err := client.DataPlaneSessions().CreateDataPlaneSession(ctx, connect.NewRequest(&ctrlv1.CreateDataPlaneSessionRequest{
	Metadata:        &ctrlv1.CommandMetadata{CommandId: kibotos.NewCommandID("platform")},
	WorkspaceId:     workspaceID,
	RequestedScopes: []ctrlv1.DataPlaneScope{ctrlv1.DataPlaneScope_DATA_PLANE_SCOPE_PROCESS},
	RequestedTtl:    durationpb.New(5 * time.Minute),
}))
if err != nil {
	log.Fatal(err)
}
endpoint := response.Msg.GetSession().GetEndpoint()
credential := response.Msg.GetCredential()

• A credential is valid for one Workspace and the scopes it names. It cannot create, stop, or delete a Workspace.
• It lasts 5 minutes by default and 15 minutes at most. Your backend issues the next one.
• The Agent runtime must reach the node address and trust server-ca.pem from the identity. See Calling the node.
• Treat the credential as a secret. To cut off all access to a Workspace at once, call RevokeWorkspaceDataPlane.

Mapping sessions to Kibotos objectsCopy Anchor Link

A Volume is bound to one Workspace at a time. Before you bind it to a new Workspace, delete the old Workspace and wait for the delete command with Client.WaitWorkspaceDeleted.

Idle sessionsCopy Anchor Link

Kibotos cannot save memory state, so choose by what the session needs when it continues:

Files the Agent must keep belong on the Volume. See Guarantees and limits.

Failure handlingCopy Anchor Link

Network accessCopy Anchor Link

A new Workspace has no network access, and that is the right start for most Agents.

• Open public internet access when the task needs it, and narrow it with destination rules. See Network policy.
• To send traffic through your own proxy or use a fixed outbound address, use an Egress. It requires v0.3.0 or later.
• To show a service in the Workspace to a user, create a public URL, and revoke it when you are done. Anyone with the address can use it.

Next stepsCopy Anchor Link

• Choosing an environment: get the software your Agent needs into a Workspace.
• Errors: what each failure reason means.
• Coding Agent with a persistent project: keep a project across sessions.
• Running untrusted code: limit what the code can reach and how long it runs.
• Batch creation and reclamation: create many Workspaces and clean them up.
• Operating a desktop: the screenshot and input loop.