Auto-start

Configuring relay CLI to auto-start as a background service.

Webhook Relay agent can run in the background and be managed by the operating system on Linux, Windows and MacOS. To start using the background service, first get the CLI following installation instructions.
Configuration file
When running as a background service, agent needs a configuration file. It’s a simple yaml format file.
For this file, you will need to:
​generate access token key and secret.
​create a tunnel if you need bidirectional tunnels (optional)
​create a bucket if you are going to use one-way webhook forwarding (optional)
Now, populate the file:
version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
tunnels:
  - tunnel-1-name
  - tunnel-2-name
buckets:
  - bucket-1-name
  - bucket-2-name
If no tunnels or no buckets are defined, that part of the relay service will be disabled. If no buckets and tunnels are specified, relay service will not start.
Note that you can subscribe to tunnels and buckets even before you have created them through the API/CLI/UI.
Once the relay service starts, key and secret will be encrypted.
Linux
Tu install the service, you will need to use sudo and provide a full path to relay configuration file:
sudo relay service install -c /full/path/config.yaml --user [YOUR USERNAME]
sudo relay service start
To specify credentials during install:
sudo relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]
Restart
To restart the service (if you change the configuration file
sudo relay service restart
Uninstall
To uninstall the service:
sudo relay service stop
sudo relay service uninstall
To view service logs, use journalctl:
journalctl -u relay.service -f
Windows
Make sure you have download relay CLI and created a config.yaml file.
If you are using Powershell:
.\relay-windows-amd64.exe service install -c .\config.yaml --user [YOUR USERNAME]
.\relay-windows-amd64.exe service start 
You can also just keep the config.yaml file in the same directory as relay exe file. Then, you just need to do:
.\relay-windows-amd64.exe service install
.\relay-windows-amd64.exe service start 
The agent is now installed and will be run after a system reboot.
To specify credentials during install:
.\relay-windows-amd64.exe service installl -c .\full\path\config.yaml --key [YOUR KEY] --secret [YOUR SECRET]
Restart
To restart the service (if you change the configuration file):
.\relay-windows-amd64.exe service restart
Uninstall
To uninstall the service:
.\relay-windows-amd64.exe service stop
.\relay-windows-amd64.exe service uninstall
MacOS
Execute as the user who will run the agent:
relay service install -c /full/path/config.yaml -u your-user
relay service start
To specify credentials during install:
relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]
Restart
To restart the service (if you change the configuration file):
relay service restart
Uninstall
To uninstall the service:
relay service stop
relay service uninstall
Note: The service needs to be installed from the Terminal by running its GUI interface as your current user. Only then will you be able to manage the service.
Using different region
By default agent connects to EU region. If you are using other region, specify it in the configuration:
version: "v1"
key: your-secret-key
secret: your-secret
region: au # Will use Australia region
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name
Logging
Usually logs can be viewed through journalctl:
journalctl -u relay.service -f
If you are using a Windows machine, then it’s useful to specify a log output location during install:
.\relay.exe service install -c C:\config.yaml  --logs-output C:\relay.log 
You can also specify logging level and output file in the configuration:
version: "v1"
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name
logs_output: /full/path/to/relay-agent-svc.log
log_level: info
Upgrade process
If the executable has write permissions, then to update it you only need to restart the service. Otherwise, follow these steps:
1.Stop the service and uninstall it.
2.Download the new binary following installation instructions for your platform.
3.Install and start the service.
HTTP Proxy settings
Relay can use HTTP proxy to open the tunnel:
version: "v1"
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name
logs_output: /full/path/to/relay-agent-svc.log
log_level: info
http_proxy: http://proxy-hostname:3128
Using with self-hosted Transponder
If you host an instance of Webhook Relay yourself (Transponder), add additional values to specify the server APIs:
version: "v1"
serverAddress: https://example.com
serverGRPCAddress: example.com:9302
serverTunnelAPIAddress: example.com:9800
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name

Install

Run config.yaml reference

Last modified 1mo ago