Arxi Sidecar Runtime Config

Overview

This document is generated from arxi-sidecar-config and is the canonical reference for sidecar runtime configuration semantics.

Top-Level Sections

config_version: must be 1.
api: contains major_version and must be 1.
recorder: recorder identity, schema/hash selectors, startup verification, auto-seal policy.
storage: SQLite file path.
transport: transport mode plus unix/tcp settings.
security: auth mode and token file controls.
probes (optional): liveness/readiness behavior and dependency policy.
enterprise (optional): enterprise integration policy and control-plane settings.
limits: body/header/concurrency/timeout/idempotency bounds.
signer: signer enablement and PKCS#8 key path.
logging: log level and format.

Fail-Closed Rules

Unknown fields are rejected at every config level.
hash_algorithm is fixed to sha256.
Non-loopback TCP requires security.mode = "token" and require_token_for_non_loopback = true.
Token files must be regular files, must not be symlinks, and on Unix must not grant group/other permissions.
max_header_bytes must not exceed the hard limit 65536.
Auto-seal mode requires mode-specific fields (count, duration_seconds).
probes.enterprise_health_path must be an absolute path without control characters.
probes.readiness_mode = "storage_and_enterprise" requires enterprise mode to be enabled.

Canonical Example

See Docs/generated/arxi/config/sidecar.example.toml.

Machine-Readable Artifacts

sidecar.example.toml

config_version = 1

[api]
major_version = 1

[recorder]
recorder_id = "sidecar:production-01"
hash_algorithm = "sha256"
schema_version = 1
startup_verification_depth = 100

[recorder.auto_seal]
mode = "combined"
count = 1000
duration_seconds = 300

[storage]
path = "/var/lib/arxi/arxi.sqlite3"

[transport]
mode = "tcp"

[transport.unix]
path = "/var/run/arxi/arxi.sock"

[transport.tcp]
host = "127.0.0.1"
port = 9090
allow_non_loopback = false

[security]
mode = "token"
require_token_for_non_loopback = true
token_file = "/etc/arxi/token"

[probes]
readiness_mode = "storage_only"
enterprise_health_path = "/health"
ready_fail_on_admission_saturation = true

[enterprise]
mode = "disabled"
require_writer_lease_header = true

[limits]
max_request_body_bytes = 4194304
max_attachment_bytes = 1048576
max_concurrent_requests = 64
max_queued_requests = 128
request_timeout_seconds = 30
shutdown_drain_seconds = 10
max_header_bytes = 16384
idempotency_ttl_seconds = 86400
idempotency_max_entries = 10000

[signer]
enabled = false
key_file = "/etc/arxi/signer.pem"

[logging]
level = "info"
format = "json"

sidecar.compat.json

{
  "api_major_version": 1,
  "baseline": {
    "hard_limits": {
      "max_header_bytes_hard_limit": 65536,
      "token_min_length": 32
    },
    "optional_top_level_sections": [
      "enterprise",
      "probes"
    ],
    "required_enum_values": {
      "auto_seal_mode": [
        "none",
        "after_count",
        "after_duration",
        "combined"
      ],
      "enterprise_mode": [
        "disabled",
        "self_hosted_bootstrap",
        "managed_cloud"
      ],
      "log_format": [
        "json",
        "pretty"
      ],
      "log_level": [
        "error",
        "warn",
        "info",
        "debug",
        "trace"
      ],
      "readiness_mode": [
        "storage_only",
        "storage_and_enterprise"
      ],
      "security_mode": [
        "token",
        "open"
      ],
      "transport_mode": [
        "unix",
        "tcp",
        "both"
      ]
    },
    "required_top_level_sections": [
      "config_version",
      "api",
      "recorder",
      "storage",
      "transport",
      "security",
      "limits",
      "signer",
      "logging"
    ]
  },
  "compatibility_policy": {
    "breaking_changes_require_major_bump": true,
    "deprecation_overlap_days_minimum": 180,
    "v1": "additive_only"
  },
  "config_version": 1
}

sidecar.schema.json

{
  "$id": "https://arxi.dev/contracts/v1/config/sidecar.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Canonical sidecar runtime configuration schema.",
  "properties": {
    "api": {
      "additionalProperties": false,
      "properties": {
        "major_version": {
          "const": 1,
          "description": "Supported sidecar API major version.",
          "type": "integer"
        }
      },
      "required": [
        "major_version"
      ],
      "type": "object"
    },
    "config_version": {
      "const": 1,
      "description": "Config document version.",
      "type": "integer"
    },
    "enterprise": {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "mode": {
                "enum": [
                  "self_hosted_bootstrap",
                  "managed_cloud"
                ]
              }
            }
          },
          "then": {
            "required": [
              "control_plane_base_url",
              "control_plane_token_file"
            ]
          }
        }
      ],
      "properties": {
        "control_plane_base_url": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "control_plane_token_file": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "default_namespace_id": {
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ]
        },
        "mode": {
          "default": "disabled",
          "enum": [
            "disabled",
            "self_hosted_bootstrap",
            "managed_cloud"
          ],
          "type": "string"
        },
        "require_writer_lease_header": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "mode",
        "require_writer_lease_header"
      ],
      "type": "object"
    },
    "limits": {
      "additionalProperties": false,
      "properties": {
        "idempotency_max_entries": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_ttl_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "max_attachment_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "max_concurrent_requests": {
          "minimum": 1,
          "type": "integer"
        },
        "max_header_bytes": {
          "maximum": 65536,
          "minimum": 1,
          "type": "integer"
        },
        "max_queued_requests": {
          "minimum": 0,
          "type": "integer"
        },
        "max_request_body_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "request_timeout_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "shutdown_drain_seconds": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "max_request_body_bytes",
        "max_attachment_bytes",
        "max_concurrent_requests",
        "max_queued_requests",
        "request_timeout_seconds",
        "shutdown_drain_seconds",
        "max_header_bytes",
        "idempotency_ttl_seconds",
        "idempotency_max_entries"
      ],
      "type": "object"
    },
    "logging": {
      "additionalProperties": false,
      "properties": {
        "format": {
          "enum": [
            "json",
            "pretty"
          ],
          "type": "string"
        },
        "level": {
          "enum": [
            "error",
            "warn",
            "info",
            "debug",
            "trace"
          ],
          "type": "string"
        }
      },
      "required": [
        "level",
        "format"
      ],
      "type": "object"
    },
    "probes": {
      "additionalProperties": false,
      "properties": {
        "enterprise_health_path": {
          "description": "Absolute path used for enterprise dependency readiness checks.",
          "minLength": 1,
          "pattern": "^/",
          "type": "string"
        },
        "readiness_mode": {
          "default": "storage_only",
          "enum": [
            "storage_only",
            "storage_and_enterprise"
          ],
          "type": "string"
        },
        "ready_fail_on_admission_saturation": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "readiness_mode",
        "enterprise_health_path",
        "ready_fail_on_admission_saturation"
      ],
      "type": "object"
    },
    "recorder": {
      "additionalProperties": false,
      "properties": {
        "auto_seal": {
          "additionalProperties": false,
          "allOf": [
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_count"
                  }
                }
              },
              "then": {
                "required": [
                  "count"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_duration"
                  }
                }
              },
              "then": {
                "required": [
                  "duration_seconds"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "combined"
                  }
                }
              },
              "then": {
                "required": [
                  "count",
                  "duration_seconds"
                ]
              }
            }
          ],
          "properties": {
            "count": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "duration_seconds": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "mode": {
              "enum": [
                "none",
                "after_count",
                "after_duration",
                "combined"
              ],
              "type": "string"
            }
          },
          "required": [
            "mode"
          ],
          "type": "object"
        },
        "hash_algorithm": {
          "const": "sha256",
          "description": "Supported hash algorithm.",
          "type": "string"
        },
        "recorder_id": {
          "description": "Recorder identifier.",
          "maxLength": 256,
          "minLength": 1,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
          "type": "string"
        },
        "schema_version": {
          "description": "Envelope schema version.",
          "minimum": 1,
          "type": "integer"
        },
        "startup_verification_depth": {
          "description": "Read-back verification depth at startup.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "recorder_id",
        "hash_algorithm",
        "schema_version",
        "startup_verification_depth",
        "auto_seal"
      ],
      "type": "object"
    },
    "security": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "token",
            "open"
          ],
          "type": "string"
        },
        "require_token_for_non_loopback": {
          "type": "boolean"
        },
        "token_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "mode",
        "require_token_for_non_loopback",
        "token_file"
      ],
      "type": "object"
    },
    "signer": {
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "key_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "enabled",
        "key_file"
      ],
      "type": "object"
    },
    "storage": {
      "additionalProperties": false,
      "properties": {
        "path": {
          "description": "SQLite store path.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "transport": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "unix",
            "tcp",
            "both"
          ],
          "type": "string"
        },
        "tcp": {
          "additionalProperties": false,
          "properties": {
            "allow_non_loopback": {
              "type": "boolean"
            },
            "host": {
              "description": "IP literal host string.",
              "minLength": 1,
              "type": "string"
            },
            "port": {
              "maximum": 65535,
              "minimum": 1,
              "type": "integer"
            }
          },
          "required": [
            "host",
            "port",
            "allow_non_loopback"
          ],
          "type": "object"
        },
        "unix": {
          "additionalProperties": false,
          "properties": {
            "path": {
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "path"
          ],
          "type": "object"
        }
      },
      "required": [
        "mode",
        "unix",
        "tcp"
      ],
      "type": "object"
    }
  },
  "required": [
    "config_version",
    "api",
    "recorder",
    "storage",
    "transport",
    "security",
    "limits",
    "signer",
    "logging"
  ],
  "title": "Arxi Sidecar Runtime Config",
  "type": "object"
}