Advanced Installation

Choose A Method

• The USB stick installation is the recommended way for a GX with 32-bit Venus OS, such as the Cerbo GX, Ekrano GX or Venus GX. See the installation page and USB stick installation.
• Use the SSH installer when you cannot use a USB stick, prefer a terminal, or the GX runs 64-bit Venus OS, such as a newer Cerbo GX or a Raspberry Pi 5. The GX needs internet.
• Use the manual GX installation when you want to check and copy the package yourself.
• Install on another Linux computer when Phaeton should not run on the GX. The GX can then take over Auto charging only after you pair Phaeton with it, which needs Venus OS 3.80 or later, and VRM Control Panel is not available.

Install With SSH

The installation page guides you step by step: it shows how to set the GX access level, a temporary root password and SSH on LAN, and shows how to connect from Windows, macOS or Linux. You need a computer on the same local network as the GX, internet on the GX, and Settings → General → Modification checks → Modifications enabled on. Remote Console through VRM does not give your computer an SSH connection to the GX.

Once you are connected and the prompt starts with root@, paste this command and leave the terminal open until it finishes:

(installer=$(mktemp) && trap 'rm -f "$installer"' EXIT && curl -fL --connect-timeout 15 --max-time 120 https://phaeton.virtunet.io/install/gx.sh -o "$installer" && sh "$installer")

If phaeton.virtunet.io cannot be reached, download the same installer straight from the download service:

(installer=$(mktemp) && trap 'rm -f "$installer"' EXIT && curl -fL --connect-timeout 15 --max-time 120 https://downloads.phaeton.virtunet.io/install/gx.sh -o "$installer" && sh "$installer")

What The Installer Does

• Checks that the device runs Venus OS on ARMv7 or ARM64, and picks the matching package.
• Checks for the tools it needs, that modifications are enabled, that web port 8088 is free, and that there is at least 64 MiB of free space in /tmp and 32 MiB in /data.
• Downloads the latest stable release, checks its signature and checksum, and stops if either does not match.
• Installs Phaeton in /data/phaeton, writes its startup script run.sh and adds a marked block to /data/rc.local, keeping your other startup commands.
• Starts Phaeton, waits for the web interface, and prints its address and the SHA-256 fingerprint of its certificate. It does not start charging.

A new installation connects to the GX over MQTT and can be opened through VRM Control Panel.

After Installing

• Open the address the installer prints, normally https://GX-IP:8088/, and compare the certificate fingerprint in your browser with the installer output before you enter a password.
• Choose your administrator username and password; no setup code is needed. Continue with First-run onboarding. If setup was already done, sign in with your existing Phaeton account.
• Your Phaeton login is separate from the GX root password and from your licensing portal account.
• Once setup works, you can turn SSH on LAN off again. Keep Modifications enabled on, so Phaeton starts after a restart. A Venus OS firmware update resets the temporary root password.
• Update Phaeton later from System → Updates. Running the installer again while Phaeton runs changes nothing.

When The SSH Installation Fails

• Connection refused, timed out or permission denied: see Connection help on the installation page.
• Download failed: check the internet connection of the GX and run the command again.
• A disabled startup file exists: turn on Modifications enabled, rename /data/rc.local.disabled back to /data/rc.local and run the installer again. If both files exist, merge their commands with your installer's help instead of overwriting either.
• Not enough free space, or web port 8088 already in use: free space, or stop the program that uses the port, and try again.
• Another installer is active: wait until it finishes. If an installation was interrupted, the message names the lock to remove once no installer runs.
• The web interface did not become ready: the installation is not complete. Read the newest log file, /data/phaeton/phaeton.YYYY-MM-DD.log, fix what it reports, and start /data/phaeton/run.sh only if Phaeton is not running.
• Phaeton is already running: the installer replaced nothing. Use System → Updates.

A message that the files were installed does not mean the charger is ready. Check the Charging page and the charger connection separately.

Manual GX Installation

Install a package by hand when you want to check it yourself. The SSH installer takes the same steps and sets up startup safely, so prefer it when you can. Use the manual steps for a new installation only; update an existing one from System → Updates.

Download And Check The Package

From the download service, download the package for your GX: phaeton-VERSION-armv7-unknown-linux-gnueabihf.tar.gz for 32-bit Venus OS, which most GX devices run, or phaeton-VERSION-aarch64-unknown-linux-gnu.tar.gz for 64-bit Venus OS, such as on a newer Cerbo GX or a Raspberry Pi 5. On the GX, uname -m shows which: armv7l or aarch64. Also download SHA256SUMS, SHA256SUMS.sig and the signing key release-signing-public.pem. On a first installation the key comes from the same service as the package, so it shows a damaged download but cannot prove the service itself; keep this copy and check later releases with it.

On a computer with OpenSSL, check the signature, then the checksum. The first command prints Verified OK, the second OK for the package; stop if either fails.

openssl dgst -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest -verify release-signing-public.pem -signature SHA256SUMS.sig SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

Copy And Start

Copy the package to the GX and sign in to it:

scp phaeton-VERSION-armv7-unknown-linux-gnueabihf.tar.gz root@GX-IP:/data/
ssh root@GX-IP

On the GX, unpack the package:

mkdir -p /data/phaeton
tar -xzf /data/phaeton-VERSION-armv7-unknown-linux-gnueabihf.tar.gz -C /data/phaeton
chmod +x /data/phaeton/phaeton
rm /data/phaeton-VERSION-armv7-unknown-linux-gnueabihf.tar.gz

Before the first start, prepare the installation the way the installers do, so it connects to the GX over MQTT and gets its VRM Control Panel route:

PHAETON_DATA_DIR=/data/phaeton /data/phaeton/phaeton --init-instance default 8088

Create the startup script. It also resumes the safety check of an in-app update that a restart interrupted:

cat >/data/phaeton/run.sh <<'EOF'
#!/bin/sh
set -e
export PHAETON_DATA_DIR=/data/phaeton
export RUST_LOG=info
cd /data/phaeton
if [ -f update-pending.json ] && [ -f update-watchdog.sh ]; then
  PHAETON_INSTALL_DIR=/data/phaeton sh /data/phaeton/update-watchdog.sh </dev/null >/dev/null 2>&1 &
fi
exec /data/phaeton/phaeton
EOF
chmod +x /data/phaeton/run.sh

Start Phaeton once to check it, open https://GX-IP:8088/, and stop it again with Ctrl+C:

/data/phaeton/run.sh

Start At Boot

Make a copy of /data/rc.local, then add the line /data/phaeton/run.sh & before its exit 0 line, or at the end when it has none. Keep every other command and do not replace the whole file. A new file needs #!/bin/sh as its first line. Make the file executable with chmod +x /data/rc.local, keep Modifications enabled on, and restart the GX.

Install On Other Linux Systems

Phaeton also runs on an always-on Linux computer in the same local network as the GX, such as a Raspberry Pi. Download the package for your platform from the download service and check it as described under Manual GX installation.

Install the program:

mkdir -p phaeton-extract
tar -xzf phaeton-VERSION-PLATFORM.tar.gz -C phaeton-extract
sudo install -m 0755 phaeton-extract/phaeton /usr/local/bin/phaeton

Start it, then open https://HOST-IP:8088/ and follow First-run onboarding:

phaeton

Phaeton keeps its settings, license and logs in ~/.local/share/phaeton of the user that runs it. To use another folder, set it when you start Phaeton:

PHAETON_DATA_DIR=/path/to/phaeton-data phaeton

• To start Phaeton at boot, add it to your system's service manager, run by the same user or with the same data folder, so it keeps its settings and license.
• Connect Phaeton to the GX by pairing it, which needs Venus OS 3.80 or later, or with Legacy Modbus; see Victron GX integration.
• With Legacy Modbus, the GX connects to Phaeton's EVCS Modbus port, 502 by default. Linux lets only privileged programs use ports below 1024, so give Phaeton that permission in your service manager.
• VRM Control Panel does not work for Phaeton on another computer; open Phaeton on the local network.
• To update, install the newer package the same way and restart Phaeton. System → Updates replaces the program file Phaeton runs from and prepares the new version next to it, so it works only when the user that runs Phaeton may write to that folder; install Phaeton in a folder that user owns if you want to update from the web UI.
• Keep the computer, the GX and the charger on a trusted local network; see Security.