Install and run

Install the xg3 Agent on a Windows host in your network that can reach both the xgress3 regional gateway and your private backends.

Install (Windows)

Run in an elevated PowerShell session (Administrator):

irm https://get.xgress3.com | iex

This downloads the release installer, verifies the binary integrity (SHA256), installs xg3agent.exe under C:\Program Files\xgress3, registers the Xg3Agent Windows service (display name xgress3 Agent), and stores agent data under C:\ProgramData\xgress3\xg3agent.

On a new enrollment, the installer waits for the service to enroll and then prints the enrollment code and agent ID in the same PowerShell window. Approve that code in the console (see Enrollment). If the agent is already enrolled (certificate on disk), the installer reports that instead.

To uninstall, use Installed apps (Settings → Apps), or run in elevated PowerShell:

irm https://get.xgress3.com/uninstall | iex

The installer also places uninstall.ps1 under C:\Program Files\xgress3 and registers that local script with Windows. Prefer Installed apps or:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Program Files\xgress3\uninstall.ps1"

Windows SmartScreen (early releases)

Release builds are not yet code-signed. On first run, Windows may show “Windows protected your PC”.

1. Click More info
2. Click Run anyway

The install then proceeds normally. This warning is expected until Authenticode signing is enabled for releases.

Production command line

Release builds connect to https://{region}.xg3.io where {region} comes from --region (default au).

Flag / setting	Meaning
--region	Region id (default au). Lowercase letters, digits, and hyphens only.
--data-dir	Directory for certificates and enrollment state. Service install default: C:\ProgramData\xgress3\xg3agent. Interactive default: ~/.xg3, or ./.xg3 if no home directory.
--no-interactive	Skip the interactive console UI; log the enrollment code at warning level (use for services).
RUST_LOG	Log verbosity (for example RUST_LOG=info). Logs are written to {data-dir}/logs/ (see below).

Example:

xg3agent --region au

On first run the agent starts enrollment. In interactive mode (default on Windows when --no-interactive is omitted), a full-screen console shows the enrollment code and prompts you to approve at console.xgress3.com. With --no-interactive, the code is logged at warning level instead. An operator approves it in the console — see Enrollment.

Log files

The agent always writes diagnostic logs to disk. Log verbosity is controlled with RUST_LOG (default info if unset).

Location: {data-dir}/logs/ — for the service install: C:\ProgramData\xgress3\xg3agent\logs

Rule	Value
Daily files	agent-YYYY-MM-DD.log (UTC date in the filename)
Size roll	10 MiB per segment; rolls to agent-YYYY-MM-DD.1.log, .2.log, … when a segment fills
Segments per day	Up to 10 (~100 MiB/day upper bound)
Retention	7 days — older files removed automatically
Console output	Interactive CLI: logs go to the file only (the screen stays clean for the status UI). Service / --no-interactive: logs go to the file and warnings also appear on stderr.

Examples:

# Default info-level logs in {data-dir}/logs/
xg3agent --region au

# More detail for tunnel or enrollment issues
$env:RUST_LOG = "xg3_agent=debug"
xg3agent --region au

On a running Windows service, set RUST_LOG in the service environment (for example via sc.exe or your deployment tooling). Logs still land under the service --data-dir.

Finding logs after install

The default service data path is C:\ProgramData\xgress3\xg3agent\logs. Open today's file, for example agent-2026-06-21.log, in Notepad or your log viewer.

Interactive console (Windows)

When you run xg3agent interactively on Windows (without --no-interactive), the agent replaces scrolling log output with a live status screen that refreshes every few seconds. Diagnostic detail is in the log files (see above), not on the console.

Press Ctrl+C to stop the agent.

The UI has three states. Header rows stay in the same positions; only the status band and values change.

Screen 1 — Enrollment

Shown before an operator approves the enrollment code. Gateway is disconnected; certificate and last-request rows show - until a cert is issued.

  xgress3 agent

  Agent ID         a1b2c3d4e5f6
  Gateway          ● disconnected
  Endpoint         au.xg3.io
  Certificate      -
                     expires -
  Last request     -

  ──────────────────────────────────────────────────────────

              Enrollment code:  7FQ9-K2M8

              Waiting for approval...
              Enter this code at console.xgress3.com

  ──────────────────────────────────────────────────────────

  Ctrl+C to quit

• Agent ID — assigned by the platform when enrollment starts.
• Endpoint — hostname from the gateway URL (for example au.xg3.io).
• Enter this code at console.xgress3.com — always this hostname; open the console and use Agents → Enroll Agent.

Screen 2 — Running

Shown after approval, certificate issuance, and a successful tunnel connection.

  xgress3 agent

  Agent ID         a1b2c3d4e5f6
  Gateway          ● connected
  Endpoint         au.xg3.io
  Certificate      SHA1 4A9F...8E9C
                     expires 2026-09-14
  Last request     2026-06-21 14:32:07

  ──────────────────────────────────────────────────────────

  Status: Running normally

  ──────────────────────────────────────────────────────────

  Ctrl+C to quit

• Certificate — SHA1 thumbprint (truncated) and expiry date of the agent client certificate.
• Last request — timestamp of the most recent HTTP request relayed through the tunnel (local time).

Screen 3 — Error (reconnecting)

Same field layout as Running, plus an error line when the tunnel drops. The screen returns to Running automatically when the tunnel reconnects — no keypress required.

  xgress3 agent

  Agent ID         a1b2c3d4e5f6
  Gateway          ● disconnected
  Endpoint         au.xg3.io
  Certificate      SHA1 4A9F...8E9C
                     expires 2026-09-14
  Last request     2026-06-21 14:32:07

  ──────────────────────────────────────────────────────────

  ⚠ Warning: Tunnel closed (drain or stream closed). Retrying in 30 seconds...

  ──────────────────────────────────────────────────────────

  Ctrl+C to quit

The Retrying in …s countdown reflects exponential backoff (1 second initially, up to 120 seconds). After a connected tunnel drops, the next retry starts at 1 second again. For deeper detail during an outage, inspect {data-dir}/logs/.

Service mode (no interactive UI)

The Xg3Agent Windows service runs with --no-interactive. It does not show the screens above while running under the service control manager.

When you install with the one-line irm https://get.xgress3.com | iex script, the installer prints the enrollment code in your PowerShell session after the service starts (or confirms the agent is already enrolled). After install, routine status is in {data-dir}/logs/ — use RUST_LOG to increase verbosity when diagnosing service issues.

See Operations for exit codes and runtime behavior.

Data directory

Protect the agent data directory. It contains private keys and enrollment secrets.

File	Purpose
agent-cert.der	Agent client certificate
agent-key.pem	Private key
agent-cert-expiry.txt	Certificate expiry (Unix time, milliseconds)
pending-enrollment.json	Temporary enrollment state between enroll and certificate issuance (includes secrets)
logs/	Rolling log files (7-day retention)

When all certificate files are present and valid, the agent resumes on restart without re-enrolling.

Windows service

The agent can run under the Windows Service Control Manager.

• Service name: Xg3Agent (shown as xgress3 Agent in Windows Services)
• Install path: C:\Program Files\xgress3\xg3agent.exe
• Data path (service): C:\ProgramData\xgress3\xg3agent
• Release example binPath: "C:\Program Files\xgress3\xg3agent.exe" service --no-interactive --region au --data-dir "C:\ProgramData\xgress3\xg3agent"
• The agent connects to https://au.xg3.io (or another region with --region) automatically.
• Stop and system shutdown request a clean exit (exit code 0).

Example:

"C:\Program Files\xgress3\xg3agent.exe" service --region au --no-interactive --data-dir "C:\ProgramData\xgress3\xg3agent"

Environment tuning

Variable	Purpose
XG3_AGENT_MAX_CONCURRENT_BACKEND_REQUESTS	Maximum concurrent backend forwards per tunnel (default 128). Increase only if your backends can handle the load.

Firewall

Allow outbound connections from the agent host to:

• The gateway host and port in your gateway URL (typically 443 for https://)
• Each backend base URL configured on services that use this agent

Agent upgrades are actioned from the Console. The updated binary is sourced directly from it the agent's current regional gateway.

No inbound firewall rules are required for the agent.

Next steps

• Enrollment — codes, approval, certificate issuance
• Operations — reconnect, console upgrade, rollback, renewal, exit codes