The Capability Sidecar

The capability sidecar runs beside every workload and holds every credential your workload uses. Your code holds none. It calls the sidecar on the loopback interface, with no credential, and the sidecar performs the call under your workload’s identity and the grants your spec declares.

Finding the sidecar

The platform sets these variables in your primary container. A variable is set only for a capability your spec grants.

Variable	Holds
VANTACLOUD_CAPABILITIES_URL	The sidecar’s base URL
VANTACLOUD_VAULT_URL	The vault capability’s URL, <base>/vault/
VANTACLOUD_STORE_URL	The store capability’s URL, <base>/store/
VANTACLOUD_DB_URL	The db capability’s URL, <base>/db/
VANTACLOUD_MODELS_URL	The models capability’s URL, <base>/models/
VANTACLOUD_ACCOUNTS_URL	The accounts capability’s URL, <base>/accounts/
VANTACLOUD_VANTANET_URL	The vantanet capability’s URL, <base>/vantanet/
VANTACLOUD_TELEMETRY_URL	The telemetry capability’s URL, <base>/telemetry/
OTEL_EXPORTER_OTLP_ENDPOINT	The telemetry capability’s URL, which every OpenTelemetry SDK reads

A GET of the base URL answers the capabilities granted and the URL of each. Read the URLs from the environment rather than writing them into your code, since the address differs between the targets your workload runs on.

A workload registered as a backend also reads the discovery document at <base>/.well-known/vantacloud.json, which names the sidecar’s own /accounts/, /models/ and /vantanet/ URLs. A backend’s code reads its addresses from it, so the same code runs on VantaCloud and beside a sidecar off it.

Refusals

A call outside your grants is refused with an RFC 9457 problem document naming the capability and the operation refused, and the code permission-denied. A call on a resource the sidecar has not yet resolved, such as in the first seconds after your workload starts, is refused with unavailable naming the capability. Retry an unavailable refusal with a backoff, and treat permission-denied as a missing grant in your spec.

vault

A grant on a secret admits the operation use. Your code sends the request it would send to the secret’s upstream to the sidecar under the secret’s name, and the sidecar sends it on with the credential added, streaming the answer back unchanged. The secret’s value never reaches your code.

Call	Body	Answers
ANY /vault/{secret}/<path>	The upstream request’s body	The upstream’s answer, streamed unchanged

The sidecar sends your method, query and headers to the upstream the secret declares, at <path> under it. It refuses with permission-denied a path outside the secret’s path prefix and a request naming another host, and it follows no redirect, answering one to your code as the upstream sent it. Headers beginning VantaCloud-Vault- are removed before the request leaves.

A grant on a key admits the operations its type offers. Every body and answer is JSON, and every byte string in them is base64.

Call	Body	Answers
POST /vault/keys/{key}/sign	data, at most 1 MiB; scheme for rsa-2048, pkcs1 or pss, pkcs1 when absent; encoding for ecdsa-p256, raw or der, raw when absent	signature, version, kid, alg
POST /vault/keys/{key}/verify	data, signature, version where known, and scheme or encoding as for sign	valid, and version, the version that verified
POST /vault/keys/{key}/encrypt	plaintext, at most 4 KiB; aad where used	ciphertext, version
POST /vault/keys/{key}/decrypt	ciphertext; aad as encrypted	plaintext, version
POST /vault/keys/{key}/wrap	key, a data key of 16 to 64 bytes; aad where used	wrapped, version
POST /vault/keys/{key}/unwrap	wrapped; aad as wrapped	key, version
GET /vault/keys/{key}		name, type, currentVersion and every version
GET /vault/keys/{key}/jwks		The key set

store

The store capability hands out access rather than carrying the data. Your code asks for an operation on an object, and moves the object with the provider directly using the URL or token it is answered.

Call	Body	Answers
POST /store/{bucket}/presign	operation, of get, put, delete and head; key; expiresIn, seconds, at most 900 and 300 when absent; contentType, for a put	url, method, headers, the headers the request carries, and expiresAt
POST /store/{bucket}/token	operations, of get and put; key; expiresIn, as above	provider, endpoint, the base URL the provider’s SDK takes, token and expiresAt
GET /store/{bucket}/list?prefix=<p>&after=<key>&limit=<n>		A page of objects, each key, size, etag and lastModified, by key, and next, the key to read the next page after
POST /store/registries/{name}/credentials	operations, of push and pull as the grant names	loginHost, username, password and expiresAt

Use a presigned URL for a single request and a token for a multipart upload or ranged reads through the provider’s SDK.

db

The db capability serves each granted database on a local endpoint. Your code connects with any driver of the database’s protocol and presents no password.

Call	Answers
GET /db/	Each granted database: its instance, database, protocol, postgres or bolt, operations and url
GET /db/{instance}/{database}	The one database

A PostgreSQL database’s url is postgresql:///<database>?host=/var/run/vantacloud/db/<instance>, a Unix socket in a volume every container of your workload mounts at /var/run/vantacloud/db. A Neo4j database’s is bolt://127.0.0.1:<port>, reached with no authentication. A connection to a database your workload holds no grant on is refused with SQLSTATE 42501.

models

Your code speaks the model endpoint to /models/ with no credential, asserting the account each call acts for, and the sidecar forwards it. A call is priced and charged to that account as any model request is.

accounts and vantanet

A workload registered as a backend speaks the public protocol’s accounts endpoint to /accounts/ and its vantanet endpoint to /vantanet/, each with no credential, and the sidecar forwards each call under the backend’s identity.

telemetry

The telemetry capability is your workload’s local OpenTelemetry collector.

Call	Body	Answers
POST /telemetry/v1/traces	OTLP ExportTraceServiceRequest, protobuf or JSON	OTLP ExportTraceServiceResponse
POST /telemetry/v1/logs	OTLP ExportLogsServiceRequest	OTLP ExportLogsServiceResponse
POST /telemetry/v1/metrics	OTLP ExportMetricsServiceRequest	OTLP ExportMetricsServiceResponse

The sidecar accepts every record it can parse and stamps its resource with vantacloud.tenant.id, vantacloud.workload.name, vantacloud.pod.id and deployment.environment.name, replacing any value your code set. It sets service.name to your spec’s observability.service where your code set none.

What the sidecar reports for you

The sidecar reports, with no code of yours, every call your code makes through it, every database connection it brokers and your probes’ results, and the platform reports your container’s CPU, memory, restarts and OOM kills, under the names Telemetry Conventions states. Observability states what each tells you.