Xeonr Developer Docs
API SpecificationEnvironments

Build Environment

POST
/containers.api.v1.EnvironmentService/BuildEnvironment

Builds a content-addressed image from an install spec on the shared BuildKit and registers it, streaming build log frames and ending with either the new Environment or a build failure. install.base_image or stages is required, every stage needs a base_image, and apt package names must be plain tokens (InvalidArgument). Base images given as tags are pinned to digests first. A context_snapshot_id builds over that workspace snapshot. shared_cache dedupes identical specs across namespaces. Unimplemented without a build backend.

Access: namespace OPERATOR or above (write)

Authorization

BearerAuth
AuthorizationBearer <token>

A namespace-scoped API key (cpk_…) for machines, or a Xeonr Auth OIDC token for humans. The key's namespace and role are pinned server-side.

In: header

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/connect+json

namespace?string
Lengthlength <= 64
install*

base_image or stages is required.

runtime?string

UNSPECIFIED is stored as GVISOR. enum.defined_only = true

Value in"SANDBOX_RUNTIME_UNSPECIFIED" | "SANDBOX_RUNTIME_GVISOR" | "SANDBOX_RUNTIME_RUNC" | "SANDBOX_RUNTIME_KATA"
parameters?
Itemsitems <= 1000
outputs?
Itemsitems <= 1000
security?

opt-in root / writable rootfs; default = hardened

label?string

user-defined display name (console-required)

Lengthlength <= 4096
[key: string]?never

Response Body

application/connect+json

application/connect+json

curl -X POST "https://containers.xeonr.io/containers.api.v1.EnvironmentService/BuildEnvironment" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/connect+json" \  -d '<install/>'
{
  "done": {
    "environmentId": "string",
    "namespace": "string",
    "imageRef": "string",
    "imageDigest": "string",
    "runtime": "SANDBOX_RUNTIME_UNSPECIFIED",
    "parameters": [
      {
        "name": "string",
        "kind": "KIND_UNSPECIFIED",
        "jsonSchema": "string",
        "required": true,
        "mountPath": "string"
      }
    ],
    "outputs": [
      {
        "name": "string",
        "kind": "KIND_UNSPECIFIED",
        "path": "string",
        "maxBytes": "string",
        "required": true,
        "mimeHint": "string"
      }
    ],
    "createdAtUnix": "string",
    "pinned": true,
    "security": {
      "runAsRoot": true,
      "writableRootfs": true
    },
    "label": "string",
    "buildSpec": {
      "baseImage": "string",
      "steps": [
        {
          "argv": [
            "string"
          ]
        }
      ],
      "cacheInputs": [
        {
          "name": "string",
          "content": null
        }
      ],
      "sharedCache": true,
      "contextSnapshotId": "string",
      "stages": [
        {
          "name": "string",
          "baseImage": "string",
          "packages": [
            "string"
          ],
          "workdir": "string",
          "ops": [
            {
              "copy": {
                "from": "string",
                "src": [
                  "string"
                ],
                "dst": "string"
              }
            }
          ],
          "env": {
            "property1": "string",
            "property2": "string"
          },
          "entrypoint": [
            "string"
          ]
        }
      ]
    },
    "defaultArgv": [
      "string"
    ],
    "imageEntrypoint": [
      "string"
    ]
  }
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}

Environments

The images workloads run on — register a digest-pinned image, or build a content-addressed one from an install spec.

Delete Environment POST

Deletes an Environment record. **Access:** namespace OPERATOR or above (write)