Docs

Local Setup

What this screen is for

Local Setup installs and connects the Fenwave Agent on your own machine, which is what lets local development talk to the platform.

Before you start

To do this You need
Open the installer the local-env access permission

Opening it

Tools › Local Setup.

Direct URL: /agent-cli/installer

📸 Screenshot Placeholder: The agent installer page. Mark: (1) the prerequisites section, (2) the platform selector, (3) the install command, (4) the connection status.

Overview

The Fenwave Agent Installer is an automated setup tool that installs and configures the Fenwave Agent CLI on your local machine. It handles everything — from npm package installation to device registration with Backstage — in a guided process directly from the Fenwave IDP.

What gets set up:

  • Fenwave Agent CLI installed globally via npm
  • Device registered and authenticated with Backstage
  • Fenwave DevApp image downloaded from GHCR

Prerequisites

Before starting, ensure the following are installed and running on your machine:

Requirement Version Notes
Node.js v20 or later Required to install the agent CLI
Docker Any recent version Must be running before starting the agent

Accessing the Installer

From the left sidebar, go to Tools → Local Setup (Agent Installer), or navigate directly to /agent-installer.

Installation Steps

Step 1 — Select Your Platform

Choose your operating system:

  • macOS / Linux — for Mac and Linux systems
  • Windows — for Windows 10/11

Click Continue.

Step 2 — Generate a Registration Token

Click Generate Registration Token. A secure one-time token will be generated for your device.

!!! warning “Keep your token secure” - The token is valid for 7 days and can only be used once - Do not share it or include it in source control

Step 3 — Download & Run the Installer

Click Download Installation Script. The downloaded script embeds your registration token and backend URL automatically.

macOS / Linux

Open a terminal, navigate to your download folder and run:

chmod +x install-fenwave-agent.sh && ./install-fenwave-agent.sh

Windows

Open PowerShell as Administrator, navigate to your download folder and run:

.\install-fenwave-agent.ps1

What the script does automatically:

  1. Verifies Node.js and npm are installed (v20+)
  2. Installs the Fenwave Agent CLI globally
  3. Registers your device with Backstage using the embedded token
  4. Downloads the Fenwave DevApp image from GHCR

npm permission issues

If the installer cannot write to the npm global directory, it will prompt you to choose a resolution:

  1. Install nvm (recommended) — Uses Node Version Manager for clean, permission-free global installs
  2. Configure npm user directory — Redirects global installs to ~/.npm-global (Linux/macOS) or %APPDATA%\npm (Windows)
  3. Use sudo / Run as Administrator — Not recommended due to security risks and potential file ownership issues

Step 4 — Start the Agent

Once the script completes, start the agent:

# Start in background mode (recommended)
fenwave service start

# Start in foreground mode (logs printed to terminal)
fenwave service run

The Fenwave DevApp dashboard URL will be displayed after login. Default: http://localhost:3003 (port may vary).

Useful Commands

Command Description
fenwave status Check session, device, and agent statuses
fenwave login Authenticate with Fenwave
fenwave logout Clear stored session and log out
fenwave rotate-credentials Rotate device credentials
fenwave --help View all available commands

What Was Configured Automatically

After a successful installation, the following are set up on your machine:

  • Device registered with Backstage
  • Backend URL configured
  • Fenwave DevApp image downloaded from GHCR

To register an additional device, return to the installer and click Register Another Device.

Scenario

Setting up a machine you have just been handed.

  1. Read the prerequisites before running anything. Most failed installs are a prerequisite nobody checked, and they fail late.
  2. Run the installer from Tools › Local Setup.
  3. Authenticate the agent — see Fenwave Agent › Authentication.
  4. Verify the connection rather than assuming it. An agent that installed but never connected looks identical to one that works, until you need it.
  5. If you use the desktop app, connect it — see DevApp Connection.
  6. When something misbehaves later, start at Agent Troubleshooting. Local problems are local: they are not the hosted platform, and looking there first wastes the afternoon.

When it doesn’t work

Symptom Cause How to check Fix
Local Setup is not in the submenu Missing the local-env access permission Access Explorer Ask for a role granting it
The installer fails partway An unmet prerequisite The prerequisites section Meet it, then re-run
The agent installed but nothing connects It was never authenticated Authentication Authenticate it
Local works, the platform does not see it The agent is not connected Troubleshooting Reconnect the agent

Next