#Agents

ByteOr Cloud agents are environment-scoped runtime nodes that receive deployments, report status, and upload artifacts.

#Bootstrap Model

Agent enrollment is a two-step credential model:

1. An environment-scoped enrollment token with agent:enroll scope is used once to register the node
2. The control plane returns a per-agent runtime API key that the node keeps for all subsequent operations

Do not reuse the enrollment token after registration succeeds.

#Required Environment Variables

BYTEOR_API_BASE_URL=<hosted API origin>
BYTEOR_AGENT_ID=<returned agent ID>
BYTEOR_AGENT_API_KEY=<returned runtime API key>

#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>

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

If name is omitted, the backend derives one from the host name.

Persist the response values — especially the agent ID and runtime API key.

#Runtime Operations

After enrollment, the agent uses the per-agent runtime key for:

• Heartbeat updates — periodic health reporting
• Deployment fetch — receiving deployment targeting information
• Signing-key refresh — maintaining current credential material
• Artifact upload — submitting incident bundles and snapshots

#Artifact Upload

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

The runtime key must include the agent:artifact_upload scope.

Artifact uploads enforce:

• Type validation
• Size validation
• Content-hash deduplication
• Scoped authorization
• Rate limiting (returns 429 on excess)

#Install Sequence

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 during first boot
4. Persist the returned agent ID and runtime API key
5. Start the agent service
6. Verify heartbeats appear in the Cloud control plane

#Operational Notes

• Each agent is scoped to exactly one environment
• Enrollment tokens should be short-lived and single-use
• Runtime API keys are per-agent and should be stored securely
• If an agent shows repeated 401 or 403 responses, check key scopes and environment binding

#Production Bootstrap

Install on a target host with the one-liner:

/bin/bash -c "$(curl -fsSL https://install.byteor.com/agent.sh)" -- \
  --token <ENROLLMENT_TOKEN> \
  --env prod \
  --group workers \
  --server https://cloud.byteor.com

What the script does:

1. Installs the byteor-agent binary and systemd service unit
2. Calls POST /api/v1/.../agents with host metadata (hostname, OS, arch, runtime version, labels)
3. Stores the returned agent identity and per-agent API key in /etc/byteor/agent.env
4. Enables and starts byteor-agent.service
5. The agent enters steady-state: heartbeats → deployment fetch → bundle pull → artifact upload

The script is idempotent — if /etc/byteor/agent.env already exists, it reuses the existing identity unless --force is provided.

#Agent Enrollment Sequence

  Node bootstrap                        Control Plane API
  ──────────────                        ─────────────────
       │                                       │
       │  POST /api/v1/.../agents              │
       │  Authorization: Bearer <enroll token> │
       │  { "name": "edge-node-01" }           │
       │──────────────────────────────────────▶│
       │                                       │
       │  200 OK                               │
       │  { agent_id, runtime_api_key }        │
       │◀──────────────────────────────────────│
       │                                       │
       │  Store /etc/byteor/agent.env          │
       │                                       │
       │  GET /api/v1/agents/{id}/deployment   │
       │  Authorization: Bearer <runtime key>  │
       │──────────────────────────────────────▶│
       │                                       │
       │  (heartbeats, artifact uploads, ...)  │
       │◀─────────────────────────────────────▶│