Alexandria
Getting Started

Configuration Reference

Configuration of alexandria-server and alexandria-client in the section layout (YAML) and the flat specification layout (JSON), plus lifecycle parameters and command-line flags.

Configuration Reference

Both binaries read one configuration document, in YAML (.yaml, .yml) or JSON (.json), in either of two equivalent layouts (DP-11):

  • the section layout used in config/ (common_config, auth_config, did_config, observability, plus vhub_config or client_config), and
  • the flat layout of the specification (Appendix B for the server, Appendix A.3 for the client) used in deploy/.

The document is validated at startup: the server against deploy/server.schema.json, the client against spec/schemas/config.schema.json. Paths written as file:… are resolved relative to the directory of the configuration file.


1. alexandria-server

common_config:
  hosts:
    http:
      protocol: "https"
      url: "127.0.0.1"
      port: "8443"
      internal_port: "8443"
  db:
    db_type: "SQLite"
    database: "file:../var/hub/hub.db"
    blobs: "file:../var/hub/blobs"
  connection:
    tls:
      cert: "file:../var/tls/hub.crt"
      key: "file:../var/tls/hub.key"

auth_config:
  enabled: true
  issuer: "http://127.0.0.1:9400"
  audience: "alexandria-vhub"
  algorithms: ["RS256", "ES256", "EdDSA"]
  roles_claim: "roles"
  admin_role: "vhub-admin"
  jwks_refresh: "PT10M"

did_config:
  type: "key"
  signing_key: "file:../var/hub/hub.key"

observability:
  log_level: "info"
  log_format: "auto"
  # otlp_endpoint: "http://127.0.0.1:4318"

vhub_config:
  rdf_context: "self-hosted"
  compiler: "dsl"
  clock_skew: "PT5S"
  vocab:
    max_size: 10485760
    proxy_timeout: "PT30S"
    allow_insecure_localhost: true

Fields (flat names)

FieldRequiredDescription
listenYesAddress the hub binds.
baseYesPublic base URL. It is the prefix of every IRI the hub emits ({base}/v1/namespaces/…, {base}/pub/…).
didNoHub DID. Defaults to the did:key derived from the signing key; a did:web is also supported (DP-5).
signing.keyYesEd25519 key in PKCS#8 PEM. Generated on first start if absent (PoC).
signing.verification_methodNoVerification method of the proofs; defaults to the did:key method of the key.
rdf.contextNoself-hosted serves the Appendix A.5 context at /pub/_vhub/v1/context.jsonld and uses that URL as @context; referenced uses https://w3id.org/alexandria-vhub/v1.
auth.issuers[]YesAccepted token issuers, each with iss and discovery_url.
auth.audienceYesAudience every access token must contain.
auth.algorithmsNoAllowed asymmetric signature algorithms.
auth.admin_claimNoClaim and value that mark the hub admin (default roles containing vhub-admin).
auth.jwks_cacheNoHow long a JWKS is cached (ISO 8601 duration).
vocab.max_sizeNoMaximum size in bytes of a vocabulary revision.
vocab.proxy_timeoutNoTimeout for fetching a proxy vocabulary upstream.
vocab.proxy_allowNoHost allow-list for proxy upstreams (SSRF protection).
vocab.allow_insecure_localhostNoAccept http://localhost upstreams. Laboratory only.
did_resolver.allow_insecure_localhostNoAccept http:// for a localhost did:web. Laboratory only.
storage.database, storage.blobsYesSQLite database and content-addressed blob directory.
tls.cert, tls.keyNoServe HTTPS. A self-signed laboratory certificate is generated when the files are absent. Omit both to serve plain HTTP behind a TLS proxy.
compilerNoDraft compiler: poc (JSON drafts, default) or dsl (alexandria.profiles/v1 YAML).
vendor_dirNoLocal copies of vendored profiles for the dsl compiler.
clock_skewNoTolerance applied to token and credential times.
clock_fileNoRead the current instant from a file (PoC and tests).
lifecycleNoHub-wide defaults of the lifecycle parameters below.
observability.*Nolog_level, log_format, otlp_endpoint, otlp_insecure, service_name, environment.

2. alexandria-client

common_config:
  connection:
    tls:
      ca: "file:../var/tls/hub.crt"

did_config:
  type: "key"
  hub_did: "did:key:z6Mk…"
  did_ttl: "PT6H"

observability:
  log_level: "info"
  log_format: "auto"
  audit_window: 100
  events_sink: "file:var/client/events.jsonl"

client_config:
  trust:
    hub: "https://127.0.0.1:8443"
    namespace: "demo"
    context: "https://127.0.0.1:8443/pub/_vhub/v1/context.jsonld"
  upstreams:
    dsp: "http://127.0.0.1:8282/dsp"
  listeners:
    dsp-ingress:
      bind: "127.0.0.1:9080"
    dsp-egress:
      bind: "127.0.0.1:9081"
    admin:
      bind: "127.0.0.1:9090"
  rules:
    seed: "file:deploy/rules.seed.json"
  default_action: "forward"
  unknown_agreement: "forward"
  retention:
    gc_interval: "P1D"

Fields (flat names)

FieldRequiredDefaultDescription
trust.hubYes—Base URL of the hub.
trust.namespaceYes—Namespace slug the client follows.
trust.hub_didYes—DID whose assertionMethod keys are trusted to sign listings and manifests.
trust.contextNohttps://w3id.org/alexandria-vhub/v1Expected JSON-LD context of the credentials. Set it to the hub's self-hosted URL when the hub uses rdf.context: self-hosted.
trust.did_ttlNoPT6HHow long the hub DID document is cached.
modeNoproxyproxy: the client forwards the traffic itself. validator: an external proxy (for example Envoy ext_authz) forwards and the traffic listeners only answer its checks. See examples/.
upstreams.dspIn proxy mode—DSP endpoint of the connector. Not used in validator mode.
upstreams.managementNo—Management API of the connector; required by rules on mgmt-ingress.
listeners.admin.bindYes—Admin API listener.
listeners.dsp-ingress.bindNo—Reverse proxy for inbound DSP traffic (check endpoint in validator mode).
listeners.dsp-egress.bindNo—Forward proxy for outbound DSP traffic (check endpoint in validator mode).
listeners.mgmt-ingress.bindNo—Reverse proxy for the connector management API (check endpoint in validator mode).
rules.seedNo—Initial rule set, loaded only when the persistent rule store is empty.
default_actionNoforwardWhat to do with a request no rule matches: forward or reject.
unknown_agreementNoforwardWhat to do with a transfer whose agreement was never captured.
audit.windowNo100Number of catalog responses kept for the passive audit.
retention.gc_intervalNoP1DInterval of the package garbage collector.
events.sinkYes—Where events are written, for example file:var/client/events.jsonl.

The client refuses to start on an invalid document (CONFIG_SCHEMA), an unreadable rule seed (CONFIG_RULES_SEED_UNREADABLE) or an inconsistent rule set (RULES_*), exiting with a non-zero status and the code (REQ-CLI-001).


3. Lifecycle Parameters

Lifecycle parameters travel inside every signed package manifest, so all clients of a version apply the same values. The hub defaults are:

ParameterDefaultMeaning
freshness.ttlPT24HValidity of a listing. The hub re-issues it at least every ttl / 2.
freshness.max_stalenessP7DHow long a client may keep working on an expired listing before failing closed.
propagation_windowP2DDelay between publication and new_content_from.
grace_windowP30DDefault coexistence of a breaking version with its predecessor.
min_grace_windowP7DMinimum grace window a steward may request.
sync_intervalPT6HMaximum interval between client synchronizations.
clock_skewPT5STolerated clock difference between hub and client.
lease_marginPT10SMargin the client adds around in-force boundaries.
max_concurrent_versions4Maximum number of versions in force at once.
degraded{}Per-gate behaviour (continue or reject) while the client is Degraded.

Inconsistent values are rejected with LIFECYCLE_* codes when a draft is validated.


4. Command-Line Flags

BinaryFlagDescription
both-config <path>Configuration file (default config/server.yaml or config/client.yaml).
both-clock-file <path>Read the current instant from a file (PoC and tests).
both-log-level, -log-formatOverride observability.log_level and log_format.
client-state-dir <path>Directory of the persistent state (database and packages).
client-hub-ca <path>PEM root certificate of a laboratory hub.
client-did.allow_insecure_localhostAllow http:// for a localhost did:web.

On this page