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’s remote orchestration.
What a Provider Node does:
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
systemdcurljqFFmpegNginxOpenSSLca-certificatestar / gzip• Outbound HTTPS to Castovia (agent heartbeat, config sync)
• Inbound HTTP/HTTPS only if media serving (Nginx) is required
• Sufficient disk space for recording/catch-up operations
D. Server Sizing
| Profile | vCPU | RAM | Storage | Use Case |
|---|---|---|---|---|
| Small Pilot | 2 | 4 GB | 100 GB SSD | Validation / testing |
| Small Operator | 4 | 8 GB | 500 GB SSD/NVMe | Basic recording / catch-up |
| Professional | 8+ | 16–32 GB | 2 TB+ NVMe | Multiple concurrent tasks |
| Scale | Multi-node | Per node | Dedicated storage | Origin/edge roles, CDN integration |
E. Step-by-Step Setup
- 1Create a Provider Node in Castovia admin → Servers.
- 2Choose the target operating system.
- 3Choose the node role (origin, edge, recording, transcoder, etc.).
- 4Configure recording, catch-up, and DVR storage paths.
- 5Castovia generates a unique install command with a registration token.
- 6Copy the install command from the dashboard.
- 7SSH into your Linux server and run the command with sudo/root.
- 8The agent creates or uses a dedicated castovia system user.
- 9The agent writes the config file with permission 600.
- 10The agent connects to Castovia using a secure server token.
- 11Validate heartbeat — node appears online in dashboard.
- 12Validate capabilities — FFmpeg, Nginx, disk space detected.
- 13Validate storage paths — recording/catch-up/DVR paths confirmed.
- 14Run FFmpeg dry-run — encoding capability validated.
- 15Run Nginx dry-run — media serving capability validated.
- 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_TOKENThe actual command is generated in your Castovia admin panel with a unique token for each node.
F. Authentication Model
Secure Token Authentication
Each provider node authenticates with a unique, scoped server token — one token per node, fully isolated.
Tokens can be rotated at any time from the admin dashboard without service interruption.
Admin users log into the Castovia web UI with their own credentials, completely separate from node authentication.
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:
- • Human admin password
- • Stripe API keys
- • CDN/DRM vendor credentials (unless explicitly required and encrypted)
- • App signing secrets