Agent Setup on Linux

Prerequisites

check_circleLinux on x86_64 (amd64), arm64 (64-bit ARM such as Raspberry Pi) or 32-bit ARM (armv6/armv7, such as 32-bit Raspberry Pi OS or Luckfox Pico). The Agent is a static single binary with no runtime dependencies, and the CPU architecture is detected automatically at install time
check_circleOutbound HTTPS (port 443) must be allowed (no inbound port openings or VPN required)
check_circleA WireCanal account and a canal (created on the dashboard)

Create a canal and download wirecanal.json

Create a canal on the dashboard, then download the connection file wirecanal.json from the "Setup" tab of the canal details (for step-by-step instructions with screenshots, see ① Create a canal). This file contains the connection key for that canal.

Install the Agent

In the directory where you want to place the Agent (e.g. /opt/wirecanal), run this one line. The executable wirecanal is placed in that directory, and the install is verified automatically, ending with the version display.

curl -fsSL https://download.wirecanal.com/install.sh | sh

To install manually, download https://download.wirecanal.com/latest/wirecanal-linux-amd64 (for arm64, wirecanal-linux-arm64; for 32-bit ARM, wirecanal-linux-arm), save it as wirecanal, then run chmod +x wirecanal.

On Raspberry Pi (Raspberry Pi OS, 64-bit or 32-bit) and small boards such as the Luckfox Pico, the steps on this page work as they are. All commands are identical.

Start it

Place the downloaded wirecanal.json in the same directory, then start the Agent. Since the file contains your connection key, we recommend restricting read access to yourself.

chmod 600 wirecanal.json
./wirecanal -config wirecanal.json

When the startup log shows a line like "canal <ID>: delivering access to https://<hostname> to local forwarding target <target>", the tunnel is open. The canal details on the dashboard also switch to "Connected!".

Keep it running (systemd template)

To keep it running as a server, the most reliable way is to let the OS-standard systemd manage it. Below is a template for an install under /opt/wirecanal (adjust paths and the user name to your environment).

[Unit]
Description=WireCanal Agent
After=network-online.target
Wants=network-online.target

[Service]
User=wirecanal
WorkingDirectory=/opt/wirecanal
ExecStart=/opt/wirecanal/wirecanal -config /opt/wirecanal/wirecanal.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo useradd --system --home /opt/wirecanal --shell /usr/sbin/nologin wirecanal
sudo chown -R wirecanal: /opt/wirecanal
sudo systemctl daemon-reload
sudo systemctl enable --now wirecanal
systemctl status wirecanal --no-pager

check_circleStarts automatically at OS boot, and restarts automatically 5 seconds after any stop (Restart=always).
check_circleCheck the logs with journalctl -u wirecanal -f.
check_circleFor auto-update to work, make sure the service user can write to the binary's location (the chown above). It still runs without write access, but updates then become manual (wirecanal update).

Notes

updateAuto-update is enabled from the start

The Agent replaces itself automatically when a new version is released (updates are applied only after signature verification, and if an update fails it automatically rolls back to the previous version). Only if you want to disable it, add "auto_update": false to wirecanal.json.

lanOn corporate networks that require a proxy

Just add one line to wirecanal.json, such as "proxy_url": "http://proxy.example.co.jp:8080", and outbound connections go through that proxy (environment-variable proxy settings are not consulted — only the configured value is used, for predictable behavior).

To switch the display language to Japanese, add "lang": "ja" to wirecanal.json ("lang": "en" selects English). If the connection does not come up, start with -verbose for detailed logs. You can revoke and reissue connection keys anytime from the dashboard. All options including these (multiple canals, timeouts, operation records, and more) are covered in the wirecanal.json configuration reference.

Create a canal for free Back to the setup guide

Agent setup on Linux