Agent Setup

Install and configure the CloudForge Agent on your server

Requirements

Node.js 18 or higher
Linux, macOS, or Windows (with WSL)
Outbound internet access (no inbound ports required)

Quick Install

The fastest way to install the agent:

curl -fsSL https://cloud-forge.me/install.sh | sh -s -- --token YOUR_TOKEN

This script will:

Check for Node.js (install via nvm if missing)
Install the CloudForge Agent
Set up as a system service (systemd on Linux, launchd on macOS)
Start the agent automatically

Alternative Installation Methods

npm / npx

Run directly with npx (no installation required):

npx cloudforge-agent --token YOUR_TOKEN

Or install globally:

npm install -g cloudforge-agent
cloudforge-agent --token YOUR_TOKEN

Docker

docker run -d \
  --name cloudforge-agent \
  --restart unless-stopped \
  cloudforge/agent:latest \
  --token YOUR_TOKEN

Command Line Options

Option	Description	Default
`-t, --token`	Agent token from CloudForge dashboard	Required
`-s, --server`	CloudForge server URL	`https://cloud-forge.me`
`-d, --debug`	Enable debug logging	`false`
`-V, --version`	Show version number	-
`-h, --help`	Show help	-

Environment Variables

You can configure the agent using environment variables instead of command line options:

Variable	Description
`CLOUDFORGE_TOKEN`	Agent token (alternative to --token)
`CLOUDFORGE_SERVER_URL`	Server URL (alternative to --server)
`CLOUDFORGE_DEBUG`	Set to "true" to enable debug mode

Running as a Service

Linux (systemd)

Create a systemd service file:

sudo nano /etc/systemd/system/cloudforge-agent.service

[Unit]
Description=CloudForge Agent
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
Environment="CLOUDFORGE_TOKEN=cf_your_token_here"
ExecStart=/usr/bin/npx cloudforge-agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload

sudo systemctl enable cloudforge-agent

sudo systemctl start cloudforge-agent

View logs:

sudo journalctl -u cloudforge-agent -f

macOS (launchd)

Create a launchd plist file:

nano ~/Library/LaunchAgents/me.cloud-forge.agent.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>me.cloud-forge.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/npx</string>
        <string>cloudforge-agent</string>
        <string>--token</string>
        <string>cf_your_token_here</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/me.cloud-forge.agent.plist

Security

No inbound ports - The agent only makes outbound connections
Token-based auth - Each server has a unique, one-time-visible token
TLS encryption - All communication uses HTTPS/WSS
Open source - Audit the code at GitHub

Troubleshooting

Agent won't connect

Check that your token is correct (starts with cf_)
Ensure outbound connections to cloud-forge.me:443 are allowed
Run with --debug flag to see detailed logs

Connection drops frequently

Check your network stability
The agent will automatically reconnect on disconnect
If running as a service, ensure it's configured to restart

Terminal is slow

Check the latency to cloud-forge.me
Consider using a server in a region closer to you

Quick Start Claude Code Setup