Fenwave Agent

The Fenwave Agent is a CLI tool for managing Docker containers and local development environments. It integrates with the Fenwave platform for seamless developer experience.

Prerequisites

• Docker Desktop (version 20.10 or later)
• Node.js (version 20 or later)
• Fenwave Platform Access - Valid credentials from your organization

Installation

npm install -g @fenwave/agent

Quick Start

1. Initialize the Agent

Get your registration token from the Fenwave platform, then run:

fenwave init --token <your-registration-token>

2. Authenticate

fenwave login

This opens a browser for authentication. After successful auth, you'll be prompted to start the agent.

3. Start the Agent

Background mode (recommended for production):

fenwave service start

Foreground mode (for development):

fenwave service run

4. Access the Dashboard

Open your browser to http://localhost:3003

Commands

Authentication

| Command | Description | |---------|-------------| | fenwave login | Authenticate with Backstage (does not start agent) | | fenwave logout | Clear session and stop agent if running | | fenwave status | Check agent and registration status |

Service Management

| Command | Description | |---------|-------------| | fenwave service start | Start agent as background daemon | | fenwave service run | Run agent in foreground (for development) | | fenwave service stop | Stop the running daemon | | fenwave service restart | Restart the daemon | | fenwave service status | Show daemon status (PID, port, uptime) | | fenwave service logs | View daemon logs | | fenwave service logs -f | Follow daemon logs in real-time |

Setup & Configuration

| Command | Description | |---------|-------------| | fenwave init | Interactive setup wizard | | fenwave register | Register device with Backstage | | fenwave rotate-credentials | Rotate device credentials | | fenwave uninstall | Uninstall agent and clean up |

Container Management

| Command | Description | |---------|-------------| | fenwave containers | List containers | | fenwave start <id> | Start container(s) | | fenwave stop <id> | Stop container(s) | | fenwave restart <id> | Restart container(s) | | fenwave rm <id> | Remove container(s) | | fenwave logs <id> | View container logs |

Image & Volume Management

| Command | Description | |---------|-------------| | fenwave images | List images | | fenwave pull <tag> | Pull image(s) | | fenwave rmi <id> | Remove image(s) | | fenwave volumes | List volumes | | fenwave volume-create <name> | Create volume(s) | | fenwave volume-rm <name> | Remove volume(s) |

Other Commands

| Command | Description | |---------|-------------| | fenwave info | Display agent information | | fenwave registries | List connected registries | | fenwave local-env | Manage local-env container | | fenwave --help | Show all available commands |

Architecture

The agent runs as a background daemon with the following features:

• Port Fallback: Automatically finds available port (3001-3010)
• Single Instance: Prevents multiple daemon instances
• Heartbeat: WebSocket health checks every 30 seconds
• Graceful Shutdown: Connection draining with client notification
• Log Rotation: Automatic rotation at 10MB, keeps 5 files

File Locations

~/.fenwave/
├── daemon/
│   ├── state.json      # Daemon state (PID, port, status)
│   ├── agent.pid       # Process ID file
│   └── agent.lock      # Instance lock file
├── logs/
│   ├── agent.log       # Main log file
│   └── agent.error.log # Error log file
├── session/
│   └── config.json     # Session credentials
├── config/
│   └── agent.json      # Agent configuration
└── ws-token            # WebSocket auth token

Dashboard Features

• Container management (start, stop, restart, logs)
• Docker image management
• Volume management
• Registry connections
• Real-time metrics
• Terminal access to containers

Troubleshooting

Agent won't start?

• Ensure Docker Desktop is running
• Check if another instance is running: fenwave service status
• Check logs: fenwave service logs
• Try stopping and starting: fenwave service stop && fenwave service start

Port already in use?

• The agent will automatically try ports 3001-3010
• Check which port is being used: fenwave service status

Authentication issues?

• Run fenwave logout then fenwave login
• Ensure Backstage is running and accessible

View logs for debugging:

fenwave service logs -f

Need help?

• Run fenwave --help for command options
• Contact your Fenwave administrator

Development

Local Testing

To test the agent locally before publishing:

# Navigate to the agent directory
cd fenwave-agent

# Create a global symlink to this local package
npm link

# Now 'fenwave' command will use your local code
fenwave init --token YOUR_TOKEN --backend-url http://localhost:7007

When you're done testing:

# Remove the global symlink
npm unlink -g @fenwave/agent

Running in Development Mode

# Run agent in foreground with debug output
fenwave --debug service run

Publishing

To publish a new version:

# Bump version (patch/minor/major)
npm version patch

# Publish to npm
npm publish --access public

License

Copyright 2025 Fenwave. All rights reserved. See LICENSE for details.