One Command. Fully Secured.
The CASTOVIA agent installs in under 60 seconds, handles security automatically, and communicates with CASTOVIA Cloud over encrypted channels. No manual firewall rules, no SSH keys, no VPN.
The Installation Command Explained
Exactly what happens when you run the one-line installer on your Linux server.
What the Command Does
The one-line install command you copy from the CASTOVIA admin dashboard performs the following steps on your Linux server:
The Actual Command
The command you see in your admin dashboard looks like this:
curl -sSL https://install.castovia.com/agent | sudo bash -s -- --token YOUR_SERVER_TOKENYOUR_SERVER_TOKEN is a unique, single-use token generated per node. It expires after 24 hours if unused.
What the Agent Does NOT Do
Clear boundaries. The agent is deliberately limited in scope.
Security — Built In, Not Bolted On
Every security measure is automatic. No manual configuration required.
Server Token Authentication
automaticEvery node gets a unique, cryptographically random server token (256-bit). This token is generated in the CASTOVIA admin when you create a node. It is used once during registration and then replaced by a rotating TLS client certificate.
TLS 1.3 Encryption
automaticAll communication between the agent and CASTOVIA Cloud uses TLS 1.3. The agent validates the CASTOVIA certificate chain against a pinned root CA — no trust in the system certificate store. Man-in-the-middle attacks are not possible.
Firewall Requirements
automaticThe agent only needs outbound HTTPS (port 443) to CASTOVIA Cloud. No inbound ports need to be opened. Your server firewall rules remain untouched — the agent does not modify iptables, nftables, or firewalld.
No Root Access Required at Runtime
automaticThe agent runs as a dedicated unprivileged user (castovia-agent). It only needs root during installation (to create the systemd service). At runtime, it operates with minimal permissions — read access to stream sources, write access to its own cache directory.
Automatic Certificate Rotation
automaticClient certificates rotate every 7 days. The agent handles renewal transparently. If a certificate expires (e.g., server was offline), the agent uses a secure re-enrollment flow that requires approval in the CASTOVIA admin.
Health Monitoring & Self-Healing
automaticThe agent monitors its own health. If it crashes, systemd restarts it within 5 seconds. If it cannot reach CASTOVIA Cloud, it continues serving cached configuration and queues metrics for later delivery.
Communication Protocol
How data flows between your server and CASTOVIA Cloud.
CASTOVIA Cloud → Agent (Configuration Push)
Technical: Configuration is delivered as signed JSON payloads. The agent validates each payload before applying. No raw SQL, no shell commands — only structured configuration.
Agent → CASTOVIA Cloud (Telemetry)
Technical: Telemetry is sent every 30 seconds via HTTPS POST. Payload is compressed (gzip) and encrypted. Average size: 2–5 KB per interval.
Network Summary
| Aspect | Detail |
|---|---|
| Protocol | HTTPS (TLS 1.3) with certificate pinning |
| Outbound Port | 443 (HTTPS only) |
| Inbound Ports | None required by CASTOVIA |
| Heartbeat | Every 30 seconds (2–5 KB compressed) |
| Authentication | Rotating TLS client certificates (7-day rotation) |
| Bandwidth | < 1 MB/hour for management traffic |
| Offline Behavior | Serves cached config, queues telemetry, auto-reconnects |
| Stream Traffic | Never routed through CASTOVIA — stays on your network |
Clean Uninstall
If you remove a node, the agent cleans up completely:
sudo castovia-agent uninstall --purge