Environment Variables

    This page covers the public environment-variable contract for Cloud API, worker, and agent processes. Variables are startup configuration, not dynamic runtime toggles.

    All configuration for the ByteOr Cloud API server, worker, and agent is driven by environment variables. Variables are read once at process startup; changes require a restart.

    Core Service Configuration

    These variables configure the API and worker processes in all deployment modes.

    VariableDefaultDescription
    BYTEOR_CLOUD_DEPLOYMENT_MODEcombinedRun mode. api starts only the HTTP API, worker starts only the background job processor, combined starts both in a single process.
    BYTEOR_CLOUD_API_BIND_ADDR0.0.0.0:8080Socket address the API server listens on.
    BYTEOR_CLOUD_WORKER_BIND_ADDR0.0.0.0:8081Socket address the worker health/metrics server listens on.
    BYTEOR_CLOUD_API_PUBLIC_BASE_URL—Public URL used to generate callback URLs, HATEOAS links, and OAuth redirect URIs (for example, https://api.byteor.com).
    BYTEOR_CLOUD_DATABASE_URL—PostgreSQL connection string. Supports postgres:// and postgresql:// schemes.
    BYTEOR_CLOUD_DATABASE_SCHEMApublicPostgreSQL schema to use for all tables. Useful for multi-tenant hosting or test isolation.

    Fallback Aliases

    For simpler single-process deployments, these aliases set both the API and worker values at once. Explicit _API_ or _WORKER_ variants take precedence.

    VariableResolves To
    BYTEOR_CLOUD_BIND_ADDRBYTEOR_CLOUD_API_BIND_ADDR and BYTEOR_CLOUD_WORKER_BIND_ADDR
    BYTEOR_CLOUD_PUBLIC_BASE_URLBYTEOR_CLOUD_API_PUBLIC_BASE_URL

    Development Helpers

    Used only during local development. Do not set in production.

    VariableDefaultDescription
    BYTEOR_CLOUD_RUN_DEMO_AGENTSfalseWhen true, the process spawns simulated agents that register, heartbeat, and upload artifacts against the local API. Useful for end-to-end testing without physical agent nodes.
    BYTEOR_CLOUD_DEMO_API_BASE_URLhttp://localhost:8080Base URL the demo agents use to reach the API. Override when running the API behind a proxy or in a container network.

    Hosted SaaS Convention

    Hosted SaaS references in the current public material use the cloud.byteor.com family for the UI and the api.byteor.com family for API-facing configuration. Keep those origins aligned across deployment manifests, installer flows, and agent bootstrap material.

    Agent Runtime

    These variables are injected into the agent process by the enrollment flow or set manually in self-hosted environments.

    VariableDefaultDescription
    BYTEOR_API_BASE_URL—Base URL of the ByteOr Cloud API the agent connects to (for example, https://api.byteor.com).
    BYTEOR_AGENT_ID—Unique identifier assigned to this agent during enrollment.
    BYTEOR_AGENT_API_KEY—Long-lived API key used to authenticate heartbeat, artifact, and deployment status calls. Treat as a secret.
    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index