tech.xns/relayer

Poll the status of a claim session. Checks every 10 seconds. States: STATE_1 (pending — user has not yet opened the claim URL), STATE_2 (in progress — user is completing the claim in browser), STATE_3 (completed — claim successful). Automatically proceeds when STATE_3 is reached.

Poll to check if the user has verified their email address. Automatically polls every 15 seconds for up to 30 minutes. Returns immediately if already verified. If the email has no account, indicates registration is needed.

Check system prerequisites for XNS Relayer installation: Docker availability (local or remote via DOCKER_HOST / ssh:// context), required ports (8888, 9000), an existing xns-relayer installation, disk space, and network connectivity to console.xns.tech and auth.xns.tech. Run this first before any other relayer tool.

Check the health of all Relayer services: UI (port 8888), S3 gateway (port 9000), HostIO, and the monitoring sidecars (Prometheus + Grafana containers). Polls every 10 seconds for up to 300 seconds. Reports each component status individually and names any unhealthy component; a missing monitoring stack reports as degraded (dashboards empty) without blocking the install flow. Targets the machine the Docker daemon runs on (auto-detected from the Docker context — supports remote ssh:// Docker hosts); pass host to override. Note: HostIO health status is unknown until OIDC authentication is completed.

Configure VPD (Virtual Private Datacenter) host selection for the Relayer, or preview it with dry_run. Use defaults ("true" for both expressions) or a CEL expression filtering hosts by tags. The Relayer requires a minimum of 10 data hosts and 20 parity hosts — if too few match, broaden the criteria. Requires OIDC sign-in (same session as get_host_tags).

List the adjustable Relayer settings: worker/concurrency tuning, backup schedule, and cost center (CCID). Returns current value, default, type, and guidance per setting. Use before update_settings. Requires OIDC sign-in (same session as the other tools).

Get the available host tags for VPD (Virtual Private Datacenter) configuration, plus the currently applied VPD host selection. Translate tags into plain-language options for the operator — never show raw CEL expressions. Requires OIDC sign-in on first use (the user will be prompted to sign in via browser).

Install and start the XNS Relayer. By default fetches the canonical beta channel bundle — relayer + the Prometheus/Grafana monitoring stack — from releases.scpri.me (anonymous pull) and writes a .env, then runs docker compose up -d — the user does NOT need to author any file. Falls back to a bundled copy of the bundle if the fetch fails. Pass compose_url only to override with a custom compose.

Manage Relayer configuration backups: list archives, start a backup, restore from an archive, or delete one. Restore OVERWRITES current state and restarts services — always confirm with the operator and state which archive and components first. Backups must be enabled (BACKUP_ENABLED) for list/start.

Register a new XNS account with an email and password. After registration, the user must verify their email at auth.xns.tech by clicking the link sent to their inbox. Use check_email_verified to poll for verification status. If the email already has an account, you can skip to install_relayer.

Restart a Relayer service (hostio, gateway, s3gateway, database) or all services. Disruptive: in-flight S3 requests will fail during the restart — confirm with the operator before calling. Verify recovery afterwards with check_relayer_health.

Provision S3 IAM credentials for the XNS CLI. Creates an IAM user in the Relayer and writes ~/.xns/credentials so that `xns ls` and other S3 verbs work without further configuration. Call once after check_claim_status reaches STATE_3.

Start a claim session to link this Relayer installation to an XNS account. Returns a claim URL that the user must open in a browser to complete the claim. The claim has an expiration time. After calling this, use check_claim_status to monitor claim progress.

Update adjustable Relayer settings (see describe_settings for the allowed set). Pass a map of setting name to new value, e.g. {"HOSTIO_UPLOAD_WORKERS": 20}. Returns require_restart — if true, follow up with restart_service after confirming with the operator. Changing CostCenter re-bills to a different cost center; always confirm first.

Verify the S3-compatible storage gateway is working by performing a round-trip test: create a test bucket, upload a small object, download it, and compare. IMPORTANT: you must supply fullaccess credentials — the admin key pair created via the Relayer UI IAM page (not a read-only or bucket-scoped key). By default targets port 9000 on the machine the Docker daemon runs on (auto-detected from the Docker context — supports remote ssh:// Docker hosts); pass endpoint to override with an explicit IP when auto-detection cannot reach the host.