Hardware Onboarding

Private Stack Exposure

Remote benchmark workers must reach the Metrum Insights control plane over a public URL. When you run a private or local stack, expose PostgREST before launch and use the public HTTPS URL for METRUM_PUBLIC_API_URL, INSIGHTS_API_URL, and INSIGHTS_CONTROL_PLANE_URL:

cloudflared tunnel --url http://localhost:${POSTGREST_PORT:-3000}
export METRUM_PUBLIC_API_URL="https://<cloudflared-host>.trycloudflare.com"
export INSIGHTS_API_URL="$METRUM_PUBLIC_API_URL"
export INSIGHTS_CONTROL_PLANE_URL="$METRUM_PUBLIC_API_URL"
curl -fsS "$METRUM_PUBLIC_API_URL/" >/dev/null

Do not give a remote worker localhost, 127.0.0.1, host.docker.internal, or a private-only DNS name. Keep the tunnel alive through onboarding, polling, result upload, and teardown; expose any private package/WebUI endpoint through a public URL too when the worker downloads artifacts from that stack.

The WebUI origin must also be publicly reachable when using generated onboarding commands. Set INSIGHTS_PUBLIC_URL or INSIGHTS_FRONTEND_PUBLIC_URL to that public WebUI URL so the target server can fetch /api/onboarding/install-script/<token>, /api/packages, and /api/scripts/worker-startup.sh.

Use this flow for manually registered remote hosts. For SSH-accessible hardware where Metrum Insights should set up the worker and model server before running the benchmark, see Bring Your Own Hardware. For managed Shadeform validation, prefer the WebUI-managed cloud onboarding flow in Cloud Benchmark Execution.

Set these environment variables for the examples:

export METRUM_API_URL="https://api.<control-plane-domain>"
export METRUM_WEBUI_URL="https://<control-plane-host-or-dns>"
export METRUM_JWT_TOKEN="<12-hour-db-minted-postgrest-jwt>"
export METRUM_ORG_ID="<org-uuid>"

List Servers

Lists known server instances.

curl -fsS -X POST "$METRUM_API_URL/rpc/list_server_config_instances" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"p_org_id\":\"$METRUM_ORG_ID\"}" | jq

Parameters:

Name	Required	Description
p_org_id	Yes	Organization UUID.
p_status_code	No	Optional availability/status filter.

Register Server

Registers a server configuration, GPU metadata, and an addressable server instance. This is a sequence of API calls.

curl -fsS -X POST "$METRUM_API_URL/rpc/create_server_config" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"p_org_id\":\"$METRUM_ORG_ID\",
    \"p_config_name\":\"Shadeform 1xH200\",
    \"p_config_code\":\"shadeform-h200\",
    \"p_config_type_code\":\"cloud-instance\"
  }" | jq

curl -fsS -X POST "$METRUM_API_URL/rpc/create_server_config_gpu" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"p_org_id\":\"$METRUM_ORG_ID\",
    \"p_config_code\":\"shadeform-h200\",
    \"p_vendor_code\":\"NV\",
    \"p_model_code\":\"h200\",
    \"p_gpu_count\":1
  }" | jq

curl -fsS -X POST "$METRUM_API_URL/rpc/create_server_config_instance" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"p_org_id\":\"$METRUM_ORG_ID\",
    \"p_config_code\":\"shadeform-h200\",
    \"p_hostname\":\"shadeform-h200-001\",
    \"p_availability_code\":\"available\",
    \"p_ip_address\":\"203.0.113.10\"
  }" | jq

Important parameters:

Name	Required	Description
p_config_code	Yes	Stable server config code.
p_hostname	Yes	Hostname that the worker will report.
p_config_type_code	Yes	Server config type, for example cloud-instance.
p_vendor_code	No	GPU vendor code, for example NV.
p_model_code	No	GPU model, for example h200 or rtx6000pro.
p_gpu_count	No	Number of GPUs.
p_ip_address	No	Public or private address for operator reference.

Generate Onboarding Command

Generate the worker onboarding command from the new Web UI server page. The Web UI creates a short-lived bootstrap script, downloads worker artifacts from the control plane, and joins the worker to the registered server instance.

Hosted deployments include the agent package bundle. In local self-hosted development, build it before generating bootstrap commands:

make build-agent-wheels

In current new Web UI builds, /api/onboarding/bootstrap is browser-session authenticated. Do not call it with a PostgREST bearer token. For CLI-only workflows, use the cli_join_command returned by create_server_config_instance after installing insights-cli on the host. Treat bootstrap URLs, install commands, onboarding tokens, and join commands as short-lived credentials.

Run the generated install command exactly on the target server:

curl -sSL "$INSTALL_SCRIPT_URL" | bash

For a Shadeform or other provider smoke test, the provider launch script should only invoke that generated command. Do not replace it with a custom worker-startup sequence; otherwise the test bypasses the WebUI bootstrap, package delivery, one-use script token, and agent join path that users rely on. The default script-token TTL is 10 minutes; for providers that may queue longer than that before running launch scripts, set ONBOARDING_SCRIPT_TOKEN_TTL_SECONDS on the WebUI process for the smoke test or wait until the host is reachable and then run a freshly generated command.

Check Server Readiness

Checks whether the worker has registered, heartbeated, and is ready to run.

curl -fsS -X POST "$METRUM_API_URL/rpc/validate_server_readiness" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"p_server_hostname":"shadeform-h200-001"}' | jq

Parameters:

Name	Required	Description
p_server_hostname	Yes	Hostname used during registration/onboarding.

Poll readiness with a bound. A typical validation wait is at most 20 attempts with a 15-second sleep between attempts.

Query Server Status

Lists current server status and heartbeat state.

curl -fsS "$METRUM_API_URL/v_server_current_status?limit=50" \
  -H "Authorization: Bearer $METRUM_JWT_TOKEN" | jq

Query parameters:

Name	Required	Description
limit	No	Maximum status rows to return.