API overview

The Kibotos API lets your own programs create and use Workspaces and operate the deployment without going through kibo. This page introduces the packages, the two endpoints and their protocol, shows a first request, and points to the page that explains each service.

OverviewCopy Anchor Link

The API is a set of protobuf services that any language with a Connect, gRPC, or gRPC-Web client can call. Choose it over kibo when a program needs the full feature set or a compatibility commitment: the flags and output of kibo are outside that commitment.

The pages in this section cover:

• Authentication: obtaining an Operator identity and the TLS settings for both endpoints.
• Write operations and errors: capabilities, command IDs, expected revisions, and the error format.
• Data plane: session credentials and calling the node that runs a Workspace.

For Workspaces, generations, Volumes, and their states, see Core concepts. For when data is kept, see Guarantees and limits.

A first requestCopy Anchor Link

This request queries the server's capabilities with curl and an existing kibo context identity. It also confirms that the certificates and the address are correct:

ctx="${KIBO_CONTEXT_DIR:-$HOME/.config/kibo/context}"
cert=$(ls "$ctx"/identity-*.pem)
curl --http2 --tlsv1.3 \
  --cert "$cert" --key "${cert%.pem}.key" --cacert "$ctx/server-ca.pem" \
  -H 'Content-Type: application/json' --data '{}' \
  https://ctrl.example.com:18092/kibotos.ctrl.v1.ServerInfoService/GetServerInfo

The response contains the source revision the server was built from and its list of capability names. A program of your own uses an identity of its own; see Authentication. Go programs build this client from the identity with the Go SDK.

Packages and endpointsCopy Anchor Link

Proto packagesCopy Anchor Link

The interface definitions are under proto/ in the Kibotos repository:

Every service, method, message, and enum of these packages is listed in the API reference, generated from the proto files and their comments.

The first three packages and the kibotos.service.v1 types used on the data plane carry a compatibility commitment. See Compatibility commitments.

Two endpointsCopy Anchor Link

Files, processes, the desktop, and service connections of a Workspace go directly to the node that runs it. Everything else goes to ctrl:

                 mTLS (Operator identity)                  Bearer (session credential)
Third-party ──────────────────────────► ctrl              ───────────────────────► node data plane
program    Workspace API / Operator API / enrollment      files / processes / desktop / service connections / /v1/files

ProtocolCopy Anchor Link

Both endpoints use the Connect protocol, HTTP/2 over TLS 1.3.

• Request format: POST https://<host>/<package>.<Service>/<Method>.
• The Content-Type of a unary call can be application/proto or application/json. Streaming calls use application/connect+proto or application/connect+json.
• The server is implemented with connect-go and also accepts gRPC and gRPC-Web. The examples in these pages use the Connect protocol.
• No extra request headers are needed. There is no API version header and no User-Agent requirement. Client and server compatibility is determined through the capability list. See Write operations and errors.
• The size of each request message is limited by ctrl, measured after decompression in the encoding used: 16 MiB for ArtifactPublicationService, 64 KiB for EnrollmentService, and 4 MiB for other services. Larger messages return resource_exhausted. These limits are higher than the largest request each service accepts.
• Streaming methods on the node data plane need HTTP/2. A single message of a service connection (ServiceConnectionService.Connect) is at most 32 KiB.

Service mapCopy Anchor Link

Each service name links to its generated reference page, which lists its methods, messages, and enums. The topic page explains what the service does, its preconditions, and its results. On the Workspace topic pages, the API details are in the section "With the API", after the kibo usage.

Workspace API (kibotos.ctrl.v1)Copy Anchor Link

These services run on ctrl.

Data-plane servicesCopy Anchor Link

These services are defined in ctrl.proto but run on the node data plane, not on ctrl. Call them with a session credential at the session's endpoint, which also serves two HTTP endpoints.

Operator API (kibotos.operator.v1)Copy Anchor Link

These services run on ctrl.

Enrollment (kibotos.enrollment.v1)Copy Anchor Link

Next stepsCopy Anchor Link

• Authentication: obtain an identity for your program.
• Write operations and errors: the rules every write operation follows.
• Data plane: reach the files, processes, and services of a Workspace.
• The conformance suite under conformance/ accesses a deployed environment only through these public interfaces, and can serve as a reference implementation of how to call them.