CASTOVIA icon
CASTOVIA

Server & Agent Setup Guide

A complete operating guide for provider nodes: what they are, what server to buy, how to install the agent, and how to connect it to Castovia.

A. What is a Provider Node?

A provider node is a Linux server operated by the provider or a hosting partner. It is a dedicated machine that performs media-related tasks under Castovia\u2019s remote orchestration.

What a Provider Node does:

Records live streams to local storage
Generates catch-up / timeshift content
Runs FFmpeg transcoding jobs
Serves media via Nginx (HLS/DASH)
Reports storage usage and disk health
Sends heartbeat and health reports to Castovia
Reports installed capabilities (FFmpeg, Nginx, etc.)
Authenticates with agent token, not human password

The provider retains full control of the server hardware and network. Castovia sends safe configuration and job instructions; the node executes them and reports results.

B. Supported Operating Systems

Recommended

  • Ubuntu Server 22.04 LTS
  • Ubuntu Server 24.04 LTS
  • Debian 12 (Bookworm)

Supported with validation

  • Debian 11 (Bullseye)
  • Rocky Linux 9
  • AlmaLinux 9
  • Red Hat Enterprise Linux 9 (customer provides subscription)

Not supported as Provider Node

  • Windows Server
  • Shared hosting environments
  • NAS-only systems without Linux shell/systemd
  • Consumer routers or set-top boxes as server nodes

C. Required Packages

systemd
curl
jq
FFmpeg
Nginx
OpenSSL
ca-certificates
tar / gzip

\u2022 Outbound HTTPS to Castovia (agent heartbeat, config sync)

\u2022 Inbound HTTP/HTTPS only if media serving (Nginx) is required

\u2022 Sufficient disk space for recording/catch-up operations

D. Server Sizing

ProfilevCPURAMStorageUse Case
Small Pilot24 GB100 GB SSDValidation / testing
Small Operator48 GB500 GB SSD/NVMeBasic recording / catch-up
Professional8+16\u201332 GB2 TB+ NVMeMultiple concurrent tasks
ScaleMulti-nodePer nodeDedicated storageOrigin/edge roles, CDN integration

E. Step-by-Step Setup

  1. 1Create a Provider Node in Castovia admin → Servers.
  2. 2Choose the target operating system.
  3. 3Choose the node role (origin, edge, recording, transcoder, etc.).
  4. 4Configure recording, catch-up, and DVR storage paths.
  5. 5Castovia generates a unique install command with a registration token.
  6. 6Copy the install command from the dashboard.
  7. 7SSH into your Linux server and run the command with sudo/root.
  8. 8The agent creates or uses a dedicated castovia system user.
  9. 9The agent writes the config file with permission 600.
  10. 10The agent connects to Castovia using the agent token (not human password).
  11. 11Validate heartbeat — node appears online in dashboard.
  12. 12Validate capabilities — FFmpeg, Nginx, disk space detected.
  13. 13Validate storage paths — recording/catch-up/DVR paths confirmed.
  14. 14Run FFmpeg dry-run — encoding capability validated.
  15. 15Run Nginx dry-run — media serving capability validated.
  16. 16Mark node as ready — node is now operational.

Example Install Command

curl -sSL https://castovia.com/agent/install.sh | sudo bash -s -- --token YOUR_REGISTRATION_TOKEN

The actual command is generated in your Castovia admin panel with a unique token for each node.

F. Authentication Model

Agent Token \u2260 Human Password

The agent does NOT use a human username/password. It authenticates with a server/agent token that is scoped to a single node.

Human admins log into the Castovia web UI separately with their own email/password credentials.

Agent tokens can be rotated independently without affecting human accounts.

G. Configuration File

The agent config file is stored locally on the provider node. It contains connection details and capability flags.

Example Configuration

CASTOVIA_API_URL=https://castovia.com/api

SERVER_ID=node-ch-zrh-001

AGENT_TOKEN=cat_xxxxxxxxxxxxxxxxxxxxxx

NODE_ROLE=origin

RECORDING_PATH=/srv/castovia/recordings

CATCHUP_PATH=/srv/castovia/catchup

DVR_PATH=/srv/castovia/dvr

NGINX_CONF_DIR=/etc/nginx/castovia.d

HEARTBEAT_INTERVAL_SECONDS=30

Must NOT contain:

  • \u2022 Human admin password
  • \u2022 Stripe API keys
  • \u2022 CDN/DRM vendor credentials (unless explicitly required and encrypted)
  • \u2022 App signing secrets

H. Security Rules

Server Hardening

Config file: chmod 600
Dedicated castovia system user
SSH: key-based only, no password auth
Firewall: restrict ports to necessary services
TLS for all external connections
No Nginx directory listing
Rotate agent token immediately if leaked
Keep FFmpeg, Nginx, and OS packages updated