← Blog Security & BYOC architecture • 9 min read What actually happens on your server when you connect Railyard: a line-by-line audit of our Docker, Caddy, firewall and zero-lock-in architecture
Most DevOps engineers who won’t try a PaaS agent aren’t objecting to the idea of one. They’re objecting to not knowing what it does: what gets installed, what ports open, whether it phones home or accepts connections, and what’s left behind if they walk away. That’s a reasonable thing to want answered before running anything as root on a production box. So this post skips the usual “what Railyard does for you” framing and instead describes, from the actual source, what happens between clicking Connect a server and the agent reporting ready, what changes on an ongoing basis, and what the code does on detach, since that last one doesn’t match the simplest reading of our own FAQ.
Connecting a server: the actual steps
Connecting a server is a background job that opens an SSH session with the key you provide (or one Railyard generated, if you had it create the server) and runs a fixed sequence of commands. In order:
- Docker, installed via the official
get.docker.comscript if it isn’t already present. If you’re not connecting as root, your user is added to thedockergroup so later steps don’t needsudofor every Docker call. - A 2 GB swapfile at
/swapfile, created only if no swap already exists, withvm.swappinessset to 10. Build servers get a larger one sized to leave enough headroom for an in-progress build. - UFW rules for ports 22, 80, 443 and 50052, then UFW is force-enabled if it was installed but off. If UFW isn’t installed at all, this step is skipped and logged, not silently assumed.
- Unattended security updates: the
unattended-upgradespackage is installed if missing, and/etc/apt/apt.conf.d/20auto-upgradesis written to turn on nightly package-list updates and unattended security upgrades. A restart is never triggered automatically from this step; that’s a separate, deliberate action from the server’s own page. - nixpacks, for buildpack-style deploys from a repository, unless the server is a database-only role.
- The agent itself: a TLS bundle under
/var/lib/railyard-agent/tlsif the control plane’s CA is configured (always true for Railyard’s own hosted control plane; it refuses to attach a plaintext agent rather than silently falling back), an env file at/etc/railyard-agent.env, the binary at/usr/local/bin/railyard-agent, and a systemd unit (railyard-agent.service) withRestart=always, elevated CPU and I/O priority, andOOMScoreAdjust=-900. The unit file’s own comment explains why: “the agent is the only way to reach this box, never let a runaway build or crash-looping container starve it out.” - Caddy, as
lucaslorentz/caddy-docker-proxy, run with the host’s Docker socket mounted so it can discover containers by label and route to them automatically, publishing 80 and 443. Skipped on a database-only server. - Datastores, if any are configured for that server (Postgres and Redis by default; MySQL, ClickHouse, RabbitMQ, MongoDB, InfluxDB, Elasticsearch, MinIO and Memcached are opt-in), each as its own container with a generated 40-character password, on a dedicated
railyardDocker network.
Nothing in that sequence touches a container you already had running. Named containers are specific (railyard-caddy, railyard-postgres, and so on), so the only way this collides with something already on the box is if you happened to already have a container with one of those exact names.
The firewall, precisely
The baseline UFW allow rules are 22 (SSH), 80 and 443 (Caddy), and 50052 (the agent’s own gRPC port, explained below). WireGuard, if you turn on private networking for the team, adds a UDP allow rule on port 51820. Beyond that baseline, the agent can open additional ports on its own, but only on instruction from the control plane during a heartbeat, tagged with a railyard-operator comment in the UFW rule list so they’re identifiable and removed automatically the moment they’re no longer wanted, for example when you turn off a “more public ports” setting on an app. Datastore ports (5432, 6379 and so on) are not opened by default; they stay reachable only on the private Docker network unless you explicitly turn on legacy port publishing for that server, or add your own IP under an app’s Trusted addresses, which opens a proxy scoped to that one address, not the port itself.
How the agent actually talks to the control plane
This is the part worth being precise about, because the honest answer is more nuanced than “outbound only.” The agent does two things at once. It dials out to the control plane as a gRPC client to register and send a heartbeat every 10 seconds, carrying CPU, memory, disk, process and traffic metrics, over a connection the agent always initiates. Separately, it also runs its own gRPC server, listening on 0.0.0.0:50052, which is what the UFW rule above opens. The control plane dials into that port directly for the actual work: deploys, log streaming, running a command inside a container, backup and restore, OS upgrades. That inbound path, not an outbound-only one, is what deploys and logs have run over since the beginning, and it’s still what runs them today.
There is a newer, agent-initiated streaming RPC in the protocol (Connect) built specifically to survive a server with no inbound reachability at all, behind NAT with no port forwarding. As of this writing it only proves the agent can hold one persistent outbound stream and exchange pings; it doesn’t yet carry deploys or any of the heavier RPCs. The source comment on it says this plainly: the existing dial-in path “is untouched and remains how everything actually works today.” If you’re deciding whether to open 50052 inbound, that’s the real answer: yes, today, that port being reachable from Railyard’s control plane is how the agent gets instructions.
Every call, in either direction, carries a bearer token unique to that server. On Railyard’s own hosted control plane, every agent additionally runs with mutual TLS: a per-server certificate issued from Railyard’s own certificate authority, with the server validating the control plane’s client certificate and vice versa, enforced by refusing to attach an agent in plaintext at all rather than degrading quietly. A self-hosted, single-tenant control plane without a CA configured can run the agent in a plaintext, bearer-token-only mode instead, which is a deliberate trade available to someone running their own control plane, not the default on the hosted product.
What the agent changes going forward, not just at attach
Past the initial setup, three things run continuously or in response to control-plane instructions:
WireGuard, when private networking is turned on for the team, as an interface named ry0. It installs wireguard-tools if missing, generates a keypair stored at /etc/railyard/wg.key, and adds peers (other servers of the team) by public key and endpoint as the control plane reports them, removing any peer no longer in that list. Networking covers how apps actually reference each other once this is on.
ActiveProtect, which watches for the specific pattern of a scanner: a 404 response to a request path matching known vulnerability-scanner probes (/.env, /wp-admin, xmlrpc.php, phpmyadmin, and similar). Three hits from the same IP inside a minute gets it dropped for 24 hours, enforced with an iptables chain (RAILYARD-BAN) inserted into both INPUT and DOCKER-USER, never touching a private or loopback address regardless of how it behaves. This is separate from SSH brute-force protection, which is fail2ban’s own sshd jail, installed on demand the first time ActiveProtect is turned on, not something this invents itself.
Unattended upgrades, beyond the nightly automatic pass set up at attach time, can also be triggered on demand from the server’s own page: install everything, or security updates only, with or without the restart that finishing them sometimes needs. Nothing restarts the server without that being an explicit choice on your end.
What’s never touched
Your own SSH keys stay exactly as they were. Team members’ public keys get added inside a clearly delimited block in authorized_keys (“railyard team keys: begin / end”), and only inside that block; anything you added yourself, before or after, is left alone, and removing a member removes only their line. See Teams, SSO and access for how that key list is actually managed per team. sshd_config itself is never edited directly. What the agent does add, once, is a drop-in file at /etc/ssh/sshd_config.d/00-railyard.conf that turns off password authentication and sets key-only root login, and only if your sshd_config already supports drop-ins and at least one real key-based login already exists, checked first so this can’t lock you out. It validates the config with sshd -t before reloading and reverts automatically if sshd rejects it. Set RAILYARD_SSH_HARDENING=off in the agent’s environment file to stop this entirely. Containers you already had running before connecting the server are never inspected, stopped or touched by any step above.
Detach and cancel are not the same thing, and the code treats them differently
Canceling a Railyard subscription doesn’t touch a server at all; it’s a billing-level flag, and nothing in the code ties it to stopping or detaching anything. That part holds up exactly as you’d expect: your apps are containers on a server your cloud provider bills you for, and losing access to the dashboard doesn’t reach into that server.
Clicking Detach on a specific server is a different, deliberate action, and it’s not a no-op for the apps on it. The detach controller stops every app on that server first (a graceful docker stop, giving each process its shutdown timeout, followed by docker rm -f) before asking what to do with the app records themselves (archive or delete), and only then unassigns the server from the team. Caddy itself is never stopped by this, so it keeps running, but with every backend it was routing to gone, there’s nothing left for it to serve. If you’re detaching a server specifically to hand it to someone else with its apps still running, that’s not what today’s Detach button does; it’s built for giving a server back cleanly, not for a live handoff.
Verify it yourself
None of the above should be taken on faith. On any server you’ve connected:
# the agent, running and restarting on its own if it crashes
systemctl status railyard-agent
journalctl -u railyard-agent -n 50 --no-pager
# what's actually listening, and on which interface
ss -tlnp
# the firewall rules currently applied
sudo ufw status numbered
# containers actually running, by name
docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}'
# the private network interface, if turned on
sudo wg show
# the ban chain ActiveProtect maintains
sudo iptables -L RAILYARD-BAN -n
# unattended upgrades, actually enabled
cat /etc/apt/apt.conf.d/20auto-upgrades
# the SSH drop-in, if present, and nothing else in sshd_config changed
cat /etc/ssh/sshd_config.d/00-railyard.conf 2>/dev/null || echo "not present"
If anything in a future version of this post doesn’t match what you see on your own box, that’s a bug worth reporting, not a trust exercise.
FAQ
Does the agent need an open inbound port, or is it outbound only?
Today, both: it dials out for registration and heartbeats, and it also runs its own gRPC server on port 50052 that the control plane connects into for deploys, logs and commands. An outbound-only path exists in the protocol for servers with no inbound reachability, but it doesn’t carry real commands yet; the inbound path is what actually runs things right now.
Does connecting a server touch my existing SSH access?
Your own keys and sshd_config are left alone. The agent adds team members’ keys inside its own delimited block in authorized_keys, and, if your config supports drop-ins and a working key-based login already exists, adds a drop-in file that disables password auth. Both are reversible, and the SSH hardening step can be turned off entirely with an environment variable.
What happens to my containers if I stop paying for Railyard?
Nothing. Canceling a subscription is a billing flag with no code path that stops, removes or detaches anything; your containers keep running on your own server exactly as they were.
What happens to my containers if I click Detach on a server?
They get stopped and removed, gracefully, before the server is unassigned from the team. This is different from canceling a subscription, and it’s worth knowing before you click it on a server you actually want to keep running unattended.
Is traffic between my apps on the same server private by default?
Yes, with no setup: same-server references resolve over a Docker network alias automatically. Across servers, it’s private once you turn on the team’s WireGuard network; until then, a cross-server reference still resolves, just over the app’s normal public address instead of a private one.