Agents and services

Agents run in your network; services are the public HTTP front doors that relay through an agent to your backend.

Enroll an agent

On the agent host

1. Install and start the xg3 Agent with the correct region — see Install and run.
2. Copy the enrollment code from agent output (XXXX-XXXX format).

In the console

1. Confirm the correct account and region in the header.
2. Open Agents.
3. Click Enroll Agent.
4. Enter the code and click Approve.

On success you are taken to the agent detail page. The console may show a brief “waiting for connection” message while the agent completes certificate issuance and opens its tunnel.

If approval fails:

• Expired code — use the latest code from the agent (it may have started a new enrollment).
• Wrong region — agent region must match the header region selector.
• Permission — you need access to enroll agents for this account.

See Agent enrollment for the full automatic flow after approval.

Agent detail page

From Agents, click a row to open an agent.

Area	Actions
Status	View whether the tunnel is connected
Enable / Disable	Toggle agent; confirmation dialog required
Host information	Hostname and attributes reported at enrollment
Services	Table of services using this agent
View Events	Open Event Viewer filtered to this agent — see Event Viewer

Disabled agents do not relay traffic.

Upgrade an agent

When a newer agent release is published, the agent detail page may show Upgrade to vX.X.X if:

• Your role includes permission to upgrade agents
• The agent is enrolled and reporting a version older than the latest release
• The agent tunnel is connected (upgrade is denied when offline)

On the Agents list, an older version may appear highlighted when an upgrade is available (hover for the latest version).

Click Upgrade to vX.X.X and confirm. The agent then:

1. Downloads the new binary from the regional gateway (same egress as normal operation)
2. Verifies integrity and runs a short health canary
3. On canary failure — stays on the current version and keeps the tunnel up
4. On canary success — briefly drains in-flight requests, swaps binaries, and restarts

The attempt is one-shot. Click Upgrade again while online to retry. Event Viewer records Agent Upgrade Requested, then Agent Upgraded or Agent Upgrade Failed. The Agent version on the detail page updates only after reconnect — refresh if needed.

If the button does not appear, the agent may already be current, offline, or your account may lack upgrade permission. Seamless upgrades need no extra firewall rules beyond normal gateway egress; for offline hosts use Install and run.

After a successful upgrade, the host retains xg3agent.previous.exe beside the running binary so you can restore the prior build if needed. For step-by-step rollback, see Operations — Roll back to the previous version.

Add a service

From the agent detail page, click Add Service:

Field	Guidance
Backend Base URL	Absolute http:// or https:// URL reachable from the agent host (for example https://app.internal.example/api/)
Service ID	Used in the public hostname; often auto-suggested from the backend URL — edit if needed (lowercase, hyphens)
Display name	Friendly label in the console
Authentication modes	JWT, service key, or both — see Authentication
Logging options	Optional capture of backend responses and header logging — both toggles required together; see Request logging

After creation, clients use:

https://{account_id}--{service_id}.{region}.xg3.io/{path}

One agent can front multiple services with different service IDs and backend URLs.

Service list and detail

Services in the left menu lists all services in the account.

Open a service to view or edit:

Property	Editable?
Service ID	No — fixed at creation
Agent	No — fixed at creation
Region	No — inherited from agent
Backend base URL	Yes
Authentication modes	Yes
Display name	Yes
Enabled	Yes
Logging toggles	Yes

From the service detail menu you can also choose View Events to open Event Viewer filtered to that service.

Enable/disable actions require confirmation.

Enabling a Service on an active subscription increases your billable Service count. Tier caps (Services per agent) may block enablement — see Billing.

Update a service

Change backend URL, auth modes, display name, or logging on the service detail page. Save applies immediately to new ingress requests.

The backend URL must remain a valid absolute http:// or https:// URI.

Internal backend URLs

You can point a service backend at private or internal addresses (for example http://localhost:8080, https://192.168.0.10, or https://api.mycompany.local) when the agent is allowed to reach your internal network.

By default, internal backend URLs are blocked until you enable Allow internal backend targets on the agent:

1. Open the agent detail page for the agent that will relay traffic.
2. Click Edit settings.
3. Turn on Allow internal backend targets and save.

When adding or editing a service, the console shows whether the backend URL is an internal target and may block save if the agent setting is off.

Warning: Turning off Allow internal backend targets immediately stops ingress to any service whose backend URL is internal — you do not need to change each service individually.

Private IP ranges, loopback, link-local addresses, and hostnames like localhost and *.local are treated as internal. Hostnames that resolve to private IPs through DNS may not be detected unless they match these rules.

For gateway error InternalBackendAccessDenied, see Deny codes.

Delete and reuse a service ID

You may delete a service when it is no longer needed. Deleted services stop accepting ingress traffic and disappear from normal lists.

To publish a new service under the same service ID (same public hostname):

1. Delete the old service (if still active).
2. Create a new service with that service ID, agent, and backend URL.

If a service ID is still in use by an active service, creation is rejected — update the existing service instead.

Multiple services on one agent

Typical reasons:

• Separate APIs or environments behind one egress point
• Different authentication policies per service (one JWT-only, one service-key-only)

Each service still has its own hostname and credential allowlists.

Permissions

Action	Typical requirement
Enroll agent	Enroll permission on Agents
Edit agent settings (internal backends)	Update agent permission
Create service	Create service permission
Edit service	Update service permission
Enable/disable	Agent or service manage permissions

If a button is missing, your role may not include that action — contact an account admin.

Related

• Authentication — credentials and keys after services exist
• Quickstart — end-to-end setup