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. If you do not have a code yet, use Not sure how? Read the docs in the dialog (opens the install guide in a new tab).

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.

Find agents and services

On Agents and Services, use Search in the page header to filter the table. Agents search matches agent ID, name, and hostname; Services search matches service ID, name, and backend URL. Both lists paginate — choose a Page size and use the page controls below the table.

Agent detail page

From Agents, click a row to open an agent. The page heading is Name (agent ID) when a name is set, otherwise the agent ID.

You can set an optional Name from Edit (up to 64 characters). It is not unique. Clearing it and saving removes the name. The name appears on Identity and in the Agents list; an empty name appears as an em dash. Enrollment shows when the agent was approved and by whom.

Area	Actions
Status	View whether the tunnel is connected
Enable / Disable	Toggle agent; confirmation dialog required
Host information	Hostname and attributes reported by the agent. Last update is relative (hover for the exact timestamp)
Activity	View relative times for last agent heartbeat and last HTTP request (hover for the exact timestamp)
Services	Table of services using this agent (includes last HTTP request per service)
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

You can create a service from:

• The agent detail page — click Add Service (the agent is already selected).
• The Services list — click Add Service, choose which Agent will handle the service, then continue.

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	Request logging is off by default. When on, metadata is stored in Request Lookup. Professional and Enterprise plans can also capture request body, backend response body, and response headers — 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
TLS Policy	Yes (when backend is HTTPS; requires TLS change permission)
Last HTTP request	No — relative time of the last successful request (hover for the exact timestamp; may be empty until traffic is seen)

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

Linked credentials and service keys

Service detail shows which credentials and service keys are allowed to call this service (client ID / key ID, name, enabled). If none are linked, a No Auth warning appears on the header (hover explains that no requests will reach the service).

Use Add to attach this service to one or more existing credentials or service keys (searchable list; already-linked rows are unavailable). The list only offers credentials when the service allows JWT, and service keys when it allows service-key auth. Remove on a row takes this service off that credential or key only.

After Add a Service, if your role can manage credential allowlists, the success step may offer Add Service to Credential so you can link callers without leaving the create flow.

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, logging, or TLS Policy on the service detail page (Edit → Options tabs). Save applies immediately to new ingress requests.

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

TLS Policy

Each service has a backend TLS policy that the agent applies when the backend URL is HTTPS:

Mode	Behaviour	Risk
Strict (default)	Verify the backend certificate with public CAs and the hostname	Lowest — recommended for production
Pinning	Accept the leaf certificate only if it matches any configured SHA-256 pin (SPKI or full certificate DER). CA and hostname checks are skipped	Medium — pins must stay current when certificates rotate
Insecure	Accept any backend certificate	Highest — diagnostics only; account owners can enable this by default

Pinning: add one or more pins. Choose algorithm sha256_spki or sha256_cert_der and paste the matching 64-character hex digest. Those algorithm names match the keys in a TLS error’s details (and Request Lookup), so you can copy a fingerprint from a failed handshake without translating names.

HTTP backends: TLS policy is not applied to http:// backends. The console will not let you save Pinning or Insecure while the backend URL is HTTP. If you later change an HTTPS backend to HTTP, the stored policy is left unchanged and the service detail page shows a warning: TLS Policy is ineffective due to backend using HTTP.

Changing TLS policy requires permission beyond ordinary service update; setting Insecure requires an additional grant (typically account owner).

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 (name, internal backends)	Update agent permission
Create service	Create service permission
Edit service	Update service permission
Change TLS Policy (strict / pinning)	TLS policy update permission
Set TLS Policy to Insecure	TLS insecure permission (typically account owner)
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