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], you can select no authentication on the port selected by NEMOCLAW_VLLM_PORT (8000 by default) or port 11434. Port 11435 supports no authentication only when NEMOCLAW_OLLAMA_PROXY_PORT uses a different free port. 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. Custom endpoint onboarding rejects endpoint URLs that contain userinfo, query, or fragment components instead of stripping those components. NemoClaw does not forward those components to the endpoint. Configure the provider credential separately instead of putting it in the endpoint URL.

Custom endpoint onboarding also rejects an endpoint URL that contains control characters, percent-encoded control characters, spaces within the URL, shell metacharacters, or other characters outside the URL-safe ASCII set. The URL-safe ASCII set is ASCII letters, digits, and the characters _ . / : = , @ % + - [ ] ~. NemoClaw trims ASCII spaces at the start and end of the URL before it applies these checks. It also rejects an input that is not an absolute HTTP or HTTPS URL. This rejection happens before any network request, provider registration, registry write, or sandbox and image mutation, so a rejected input changes no NemoClaw state. The inference set command applies the same rejection classes to --endpoint-url before DNS resolution. Sandbox rebuild applies the same rejection classes to recorded custom endpoint metadata and treats a violating value as unknown.

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 and pins outbound validation to the complete canonical address set. An exact trusted host can return both public and supported private addresses. NemoClaw pins every canonical answer. If any answer is a disallowed private, reserved, or special-purpose address, validation rejects the endpoint instead of discarding that answer. Wildcard or suffix matches and resolver failures also remain blocked. 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.