controlplane

Overview ¶

Command controlplane serves the wire-compatible Managed Agents REST API: resource CRUD backed by Postgres. Configuration is environment-driven:

CONTROLPLANE_ADDR     listen address (default ":8080")
DATABASE_URL          Postgres DSN (required)
CONTROLPLANE_API_KEY  bootstrap management API key (required); seeded
                      (hashed) into api_keys at startup. Changing it and
                      restarting archives the previous bootstrap key. Naming
                      a value here makes that key env-var-managed: if the
                      value already exists as a console-issued key, the row
                      loses its issuer and any expiry it carried.
BLOB_BACKEND          object storage for skill archives and files: "s3"
                      (default when empty) or "gcs". Empty with no
                      BLOB_ENDPOINT deploys without object storage (the
                      skills upload/download routes report it); naming a
                      backend and omitting its configuration is an error
BLOB_ENDPOINT         S3-compatible object storage host:port, required by
                      the s3 backend
BLOB_ACCESS_KEY / BLOB_SECRET_KEY / BLOB_BUCKET  credentials and bucket,
                      required with BLOB_ENDPOINT
BLOB_REGION           optional bucket region
BLOB_TLS              "true" for https to the endpoint (default plain)
BLOB_BUCKET_PRECREATED  "true" when the bucket is provisioned out of band:
                      startup neither checks for it nor creates it, so the
                      identity needs object permissions only. Needs
                      BLOB_REGION set, or the first object request resolves
                      the bucket location and needs that privilege anyway
                      (BLOB_BACKEND=gcs is that shape unconditionally, and
                      takes BLOB_BUCKET alone — no credential and no
                      endpoint, since it authenticates with Application
                      Default Credentials)
SECRETS_BACKEND       secrets cipher for vault credential material
                      (docs/plan/12): "openbao", "local", "gcpkms", or
                      empty to deploy without one (vault credential
                      storage reports it)
BAO_ADDR / BAO_TOKEN  OpenBao transit endpoint and token, required with
                      SECRETS_BACKEND=openbao
BAO_TRANSIT_KEY       transit key name (default "map-secrets")
SECRETS_MASTER_KEY    base64 32-byte key, required with SECRETS_BACKEND=local
SECRETS_KEY_ID        key id stored beside local-cipher ciphertext
                      (default "local-1")
GCPKMS_KEY_NAME       Cloud KMS CryptoKey resource name, required with
                      SECRETS_BACKEND=gcpkms. No credential accompanies
                      it: authentication is Application Default
                      Credentials (Workload Identity on GKE)
OTEL_EXPORTER_OTLP_ENDPOINT  optional OTLP/gRPC collector endpoint
OTEL_EXPORTER_OTLP_INSECURE  "true" to export without TLS (default TLS)

Run-once operator import (docs/plan/06_skills.md slice 3): with -import-anthropic-skills pointing at a local checkout of github.com/anthropics/skills, the binary imports the -import-skills directories as anthropic-source skills (validated exactly like uploads, date-based version from the checkout's last commit unless -import-version overrides) and exits instead of serving. Needs DATABASE_URL and the BLOB_* object storage; CONTROLPLANE_API_KEY is not required in this mode.