Skip to main content

​
Requirements

  • A systemd-based Linux distribution: Ubuntu/Debian, RHEL/CentOS/Fedora, or equivalent
  • x86_64 (amd64) or arm64 (both are fully supported)
  • Claude Code installed
  • Root/sudo access (for installation)
  • For the desktop app: a graphical session and WebKitGTK 4.1 (see Desktop app requirements)

​
Install

Every option below installs the same managed agent (turen-watchdog, turen-pkg, turen-batou, turen-updater) plus the Turen desktop app, and wires up the turen-watchdog.service systemd unit that runs on boot. You do not need a registration key up front. After installing, you can register the machine by launching the desktop app and signing in (see First run). Registration keys remain available for headless, fleet, and CI installs. Pick one of the install paths below. Detects your architecture, verifies the SHA256 checksum, installs the binaries to /usr/local/bin, installs the desktop app with a launcher entry, and starts the systemd service:
When it finishes you’ll see:
Agent-only / headless installs. To skip the desktop GUI (for example on a server or CI box), set TUREN_NO_DESKTOP=1:
On a headless box you register with a key instead of the desktop app. See Headless registration.

​
Option 2: AppImage (one-click desktop)

Download the AppImage for your architecture from the Downloads section of your Turen dashboard:
  • Turen-<version>-x86_64.AppImage on Intel/AMD machines
  • Turen-<version>-aarch64.AppImage on arm64 machines
Make it executable and double-click it (or run it). On first launch it installs the managed agent via pkexec (you’ll get a graphical authentication prompt) and then opens the Turen desktop app:
The AppImage uses polkit (pkexec) to install the agent, so your system needs polkit installed (it is present by default on most desktop distributions).

​
Option 3: .deb (Ubuntu/Debian)

Download the .deb for your architecture from the Downloads section of the dashboard, then:
The .deb declares its WebKitGTK 4.1 dependency (libwebkit2gtk-4.1-0), so apt pulls it in automatically.

​
Option 4: .rpm (RHEL/CentOS/Fedora)

Download the .rpm for your architecture from the dashboard, then:
The .rpm recommends the Fedora/RHEL WebKitGTK 4.1 package (webkit2gtk4.1). If your distribution does not pull it in automatically, install it before launching the desktop app.
The dashboard Agents download section detects your CPU architecture and offers the matching Linux installer (amd64 vs arm64 AppImage) automatically.

​
First run: register this machine

The recommended flow is keyless: after installing, launch the desktop app as your normal user (not root) and sign in or create an account. The desktop registers this machine for you over local IPC. No registration key or file editing is required.
If your account has multi-factor authentication (an authenticator app / TOTP) enrolled, the desktop prompts for the 6-digit code during sign-in. Both email/password and Google sign-in support MFA. You enroll and manage MFA factors in the dashboard under User Settings (not in the desktop app). Once you’ve signed in, the machine appears under Agents in the dashboard. See Verify Installation.
Run the desktop app as your normal user in a graphical session, not as root and not over a plain SSH shell. If you launch it as root or with no display, it shows a clear message telling you to run it as your normal user in a graphical session rather than crashing.

​
Headless registration

On a server or CI box with no desktop (or when you installed with TUREN_NO_DESKTOP=1), register with a key instead. Generate one from Devices > Settings in the dashboard, then add it to the agent environment and restart the service:
You can also pass the key straight to the one-line installer:

​
Desktop app requirements

The Turen desktop app is a graphical (GTK/WebKit) application and needs WebKitGTK 4.1 at runtime:
  • Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-0
  • Fedora/RHEL: sudo dnf install webkit2gtk4.1
The .deb and .rpm packages declare this dependency for you. If you used the one-line installer or the AppImage and the desktop app fails to launch, install the package above. The desktop app and the agent auto-update together, so you do not update the desktop app separately.

​
Using Claude Code

Once the agent is installed, open a new terminal and use Claude Code as normal:
No manual configuration is needed. The installer configures Claude Code automatically (environment variables and hooks).

​
Managing the Agent

​
Uninstall

If you installed with install.sh or the AppImage, stop the service and remove the installed files:

​
Other Platforms

Running Turen on macOS or Windows? See the macOS or Windows installation guides.