InferenceCustom Endpoints

Meet Custom Endpoint Security Requirements

View as Markdown

NemoClaw keeps provider credentials on the host and validates explicit custom endpoint URLs before saving them through security-sensitive configuration paths.

Protect Provider Credentials

The agent inside the sandbox sends requests to inference.local instead of connecting to the upstream endpoint directly. OpenShell forwards the traffic and injects the provider credential at egress. The sandbox does not receive the raw API key.

Use COMPATIBLE_API_KEY for an OpenAI-compatible endpoint that requires authentication. For an HTTP endpoint on localhost, 127.0.0.1, or [::1] and port 8000, 11434, or 11435, you can select no authentication. For non-interactive onboarding of that OpenAI-compatible endpoint, set NEMOCLAW_COMPATIBLE_AUTH_MODE=none. Use COMPATIBLE_ANTHROPIC_API_KEY for a custom Anthropic-compatible endpoint. Anthropic-compatible onboarding requires a non-empty value even when the upstream server does not authenticate requests. Use a non-empty placeholder such as dummy for an unauthenticated Anthropic-compatible endpoint.

Understand URL Validation

Explicit endpoint URLs saved through Hermes Provider setup, inference set, host-side config set, or a direct blueprint run must pass host-side server-side request forgery validation. NemoClaw rejects loopback, link-local, private, internal, reserved, and special-purpose addresses in these paths. Blocked special-purpose targets include documentation, translation, benchmarking, multicast, and metadata destinations. It also rejects public hostnames that resolve to a blocked address.

A direct blueprint run rejects endpoint URLs that contain userinfo, such as an embedded username or password, before DNS resolution. Configure the provider credential separately instead of putting it in the endpoint URL.

Managed provider defaults that do not provide an explicit custom endpoint through these paths are unaffected.

Custom endpoint onboarding has one narrower operator-controlled exception for corporate inference gateways. Set NEMOCLAW_TRUSTED_PRIVATE_HOSTS to a comma-separated list of exact hostnames or IP literals to admit an endpoint on RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local address space. NemoClaw still resolves DNS, pins the validation connection, and rejects wildcard or suffix matches, link-local metadata, reserved destinations, and resolver failures. This allowlist does not relax direct blueprint, config set, or unrelated persisted-URL validation.

NEMOCLAW_TRUSTED_PRIVATE_INFERENCE_HOSTS remains an inference-only compatibility alias. Inference onboarding combines exact entries from the generic variable and the compatibility alias. New configurations should use NEMOCLAW_TRUSTED_PRIVATE_HOSTS.

After onboarding records an admitted custom endpoint, inference set accepts that same canonical URL for a model change without resolving it again. The registry must record onboarding as the endpoint source, and the supplied URL must match exactly after normalization. Legacy entries without a source, endpoints recorded by inference set, and different URLs still pass through the full server-side request forgery validation path.

Use a Public Endpoint

For a public HTTP URL, NemoClaw stores the validated IP address so the downstream runtime cannot resolve the hostname again and reach another address.

NemoClaw rejects DNS-backed HTTPS URLs for Hermes Provider setup, host-side config set, and a direct blueprint run because it cannot pin the downstream peer address while preserving TLS Server Name Indication and host validation across the OpenShell runtime boundary. For those paths, use an HTTPS IP-literal endpoint with a certificate valid for that address, or use a public HTTP endpoint if your deployment permits unencrypted traffic.

Use the Sandbox Host Alias

NemoClaw accepts http://host.openshell.internal:<port> only when the URL includes an explicit port from 1024 through 65535. This narrow exception supports NemoClaw-managed sandbox-to-host inference routes and host-side config set writes to supported provider baseUrl fields that already use the OpenShell host bridge, including OpenClaw memory-search embedding providers. Generic config set keys continue to reject the bridge host. Accepting this URL shape does not by itself make an arbitrary local service, embedding provider, config key, or network route a supported NemoClaw integration.

For example, a containerized gateway can commonly reach a local server at http://host.openshell.internal:8000/v1. Because this name is a sandbox-internal alias, onboarding skips the host-side endpoint probe. Verify the runtime route after onboarding when you use it.

The exception is intentionally exact: use HTTP, the literal host.openshell.internal name, and an explicit unprivileged port. NemoClaw still rejects HTTPS, privileged ports, subdomains, loopback names, private IP literals, userinfo, query strings, and fragments through this path.