Agent Install Guide

    This guide covers the intended ByteOr Cloud agent bootstrap pattern for hosted SaaS environments.

    Bootstrap model

    Agent enrollment is a two-step credential model:

    1. An environment-scoped enrollment token with agent:enroll is used once to register the node.
    2. The control plane returns a per-agent runtime API key that the node keeps for heartbeats, bundle pulls, and artifact uploads.

    Do not keep using the enrollment token after registration succeeds.

    Required values

    Prefer these environment variable names in new install surfaces:

    • BYTEOR_API_BASE_URL
    • BYTEOR_AGENT_ID
    • BYTEOR_AGENT_API_KEY

    Avoid older generic names in new docs or scripts.

    Enrollment flow

    Register the agent against the project environment:

    POST /api/v1/orgs/{org_id}/projects/{project_id}/environments/{environment_id}/agents
Authorization: Bearer <environment enrollment token>

    Minimal request body:

    {
  "name": "edge-node-01"
}

    If name is omitted, the backend derives one from the host name and makes it unique.

    Persist the response values needed for runtime operation, especially the returned agent ID and runtime API key.

    Runtime operations

    After enrollment, the installed agent should use the per-agent runtime key for:

    • heartbeat updates
    • deployment fetch and activation
    • signing-key refresh
    • artifact upload

    Artifact upload is handled by:

    POST /api/v1/agents/{agent_id}/artifacts
Authorization: Bearer <agent runtime key>

    The runtime key must include the agent:artifact_upload scope for artifact submission.

    1. Install the agent binary and service unit on the target host.
    2. Set BYTEOR_API_BASE_URL to the hosted API origin.
    3. Use the environment enrollment token once during first boot or provisioning.
    4. Store BYTEOR_AGENT_ID and BYTEOR_AGENT_API_KEY returned by the control plane.
    5. Rotate the host into normal service using only the per-agent runtime key.

    Validation checks

    After installation, confirm:

    • the agent appears in the environment agent list
    • heartbeat updates are arriving
    • the latest deployment becomes visible to the agent
    • artifact upload succeeds when the agent has the correct scope

    Failure handling

    • 401 responses usually mean the runtime key is missing, expired, or wrong for the agent
    • 403 responses usually mean the key lacks the required scope
    • 429 responses indicate the agent hit abuse controls on heartbeat or artifact routes and should back off before retrying

    Operational notes

    • enrollment tokens are provisioning credentials, not steady-state runtime credentials
    • agent API keys are bound to the specific agent identity and route scope
    • use environment-specific enrollment tokens to avoid cross-environment drift
    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