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 is reserved for the proxy and is unavailable for new no-authentication endpoints. Recovery can retain an existing no-authentication route on 11435 only when the proxy has moved and no other protected service owns that port. NemoClaw rejects no-authentication endpoints on configured or recorded gateway, dashboard, agent API, Model Router, and credential-adapter ports. The shared protected proxy stays pinned to its existing backend; reuse that endpoint. Moving or removing a sandbox does not release the host-global binding. To select a different no-authentication backend, back up the sandboxes and remove the final NemoClaw gateway with the uninstaller before reinstalling. 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, Hermes 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. A 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, Hermes host-side config set, or unrelated persisted-URL validation.

NEMOCLAW_TRUSTED_PRIVATE_INFERENCE_HOSTS remains an inference-only compatibility alias. Inference onboarding combines 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, Hermes 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 Hermes host-side config set writes to supported provider baseUrl fields that already use the OpenShell host bridge. Other Hermes 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 permits only 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.