BYOC Agent Configuration

Every setting the Raklane Node Agent on your server reads, where they live, and how to change them safely.

Fri Oct 02 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

The Raklane Node Agent on your BYOC server is configured with environment variables. The install command writes the ones it needs, and every other setting has a sensible default. You only need this page to tune something: verbose logs while debugging, a different database storage location, turning off automatic updates, and so on.

Where the settings live

The agent runs as the systemd service raklane-agent, which loads its settings from:

/etc/default/raklane-agent

It's a plain KEY=VALUE file, one setting per line, readable only by root (mode 600). Right after installation it looks like this:

RAKLANE_CONTROL_PLANE_URL=https://your-raklane.example.com
RAKLANE_CONTROL_PLANE_GRPC_ADDR=your-raklane.example.com:8443
RAKLANE_ENROLLMENT_TOKEN=...
RAKLANE_AGENT_STATE_DIR=/etc/raklane-agent

Any setting that isn't in the file uses its default (see the reference below).

Changing a setting

Edit the file as root:
```
sudo nano /etc/default/raklane-agent
```
Add or change the line you need, for example:
```
RAKLANE_LOG_LEVEL=debug
```
Restart the agent so it picks up the change:
```
sudo systemctl restart raklane-agent
```

Check it came back healthy:

sudo systemctl status raklane-agent
sudo journalctl -u raklane-agent -f

Restarting the agent doesn't restart your apps or databases. They're Docker containers and keep running. The server shows Offline for a few seconds in the dashboard while the agent reconnects.

Re-running the install command rewrites this file with only the four settings above, so any settings you added are lost. Copy your custom lines somewhere first, and add them back afterwards.

Settings reference

Durations are written as a number with a unit: 30s, 5m, 1h, 1h30m. If a duration can't be parsed, the agent silently uses the default, so double-check the spelling.

Connection

These are written by the install command. You'd only change them if your Raklane installation moves to a new address.

Variable	Default	What it does
`RAKLANE_CONTROL_PLANE_URL`	— (set by install)	Your Raklane installation's URL. Used to enroll, and to download agent updates.
`RAKLANE_CONTROL_PLANE_GRPC_ADDR`	— (set by install)	`host:port` of Raklane's agent connection endpoint. The agent keeps one encrypted connection open to this address. Usually your installation's hostname on port `8443`.
`RAKLANE_ENROLLMENT_TOKEN`	— (set by install)	The one-time token used to enroll. Only read on the very first start, before the server has its certificate. After that it's ignored and can't be reused, so leaving it in the file is harmless.

Identity and storage

Variable	Default	What it does
`RAKLANE_AGENT_STATE_DIR`	`/etc/raklane-agent`	Where the agent keeps its identity: its certificate, its private key, and Raklane's CA certificate. Keep this directory private and back it up with the server.
`RAKLANE_DATABASE_VOLUME_ROOT`	`/var/lib/raklane-agent`	Where databases on this server store their data. Point it at a larger or faster disk if you need to — for example, a mounted volume at `/mnt/data/raklane`.

Change storage paths only before you use them. Moving RAKLANE_AGENT_STATE_DIR without moving its files makes the agent try to enroll again, which fails because the token is already used. Changing RAKLANE_DATABASE_VOLUME_ROOT only affects databases created afterwards. Existing databases keep their data where it was, so set this before creating any databases on the server.

Health and metrics

Variable	Default	What it does
`RAKLANE_AGENT_HEARTBEAT_INTERVAL`	`15s`	How often the agent tells Raklane it's alive. Raklane treats a server as not checking in if it hasn't heard from it in about two minutes, so keep this well under that — a longer interval makes the dashboard slower to notice problems, and too long fails the Heartbeat check.
`RAKLANE_AGENT_METRICS_INTERVAL`	`15s`	How often the agent reports CPU, memory, and container stats for the Metrics pages. Higher values send less data but make charts coarser. `0` turns metrics reporting off, which leaves your apps' Metrics tab empty; live process lists still work. See Metrics & Processes.

Automatic updates

Variable	Default	What it does
`RAKLANE_AGENT_UPDATE_INTERVAL`	`1h`	How often the agent checks whether Raklane is serving a different agent build. If so, it downloads it, verifies its checksum, and restarts into it in place (your containers keep running). A small random delay is added so many servers don't update at the same moment. `0` turns automatic updates off.

If you turn automatic updates off, keep the agent current yourself by re-running the install command now and then (remember it rewrites the settings file). An agent that falls far behind your Raklane installation may miss newer features.

Shutdown

These control what happens when the agent itself stops — for example during systemctl restart, an OS shutdown, or an automatic update.

Variable	Default	What it does
`RAKLANE_AGENT_SHUTDOWN_WARN_PERIOD`	`0`	How long the agent waits after being asked to stop before it starts shutting down. Gives in-flight work (such as a relayed connection) a moment to finish.
`RAKLANE_AGENT_SHUTDOWN_TIMEOUT`	`10s`	The longest any single shutdown step may take before it's cut off.

Logging

Variable	Default	What it does
`RAKLANE_LOG_LEVEL`	`info`	How much the agent logs: `debug`, `info`, `warn`, or `error`. Use `debug` while troubleshooting, then set it back.
`RAKLANE_LOG_FORMAT`	`json`	`json` writes one JSON object per line, which suits log shippers. `text` writes compact, human-readable lines, which are easier to read in `journalctl`.

Common recipes

Read the agent's logs comfortably while debugging:

RAKLANE_LOG_LEVEL=debug
RAKLANE_LOG_FORMAT=text

Store database data on a separate disk (before creating any databases):

RAKLANE_DATABASE_VOLUME_ROOT=/mnt/data/raklane

Pin the agent version (no automatic updates):

RAKLANE_AGENT_UPDATE_INTERVAL=0

Your Raklane installation moved to a new address: update both connection settings, then restart.

RAKLANE_CONTROL_PLANE_URL=https://new-raklane.example.com
RAKLANE_CONTROL_PLANE_GRPC_ADDR=new-raklane.example.com:8443

Remember to run sudo systemctl restart raklane-agent after any change.

Settings that aren't on the agent

A few things are decided by your Raklane installation, not by the agent, so you can't change them from your server:

Your apps' default URL domain (the BYOC domain in my-app.203.0.113.10.byoc.example.com).
How long Raklane waits for a heartbeat before a server counts as not checking in.
Whether external databases are relayed through Raklane or reached directly at your server.
The image registry your server pulls from.

Ask whoever operates your Raklane installation if you need any of these changed.