Skip to main content
Secrets are a secure way to store and use sensitive values — such as API keys, tokens, and passwords — inside a Novita Sandbox. They let code running in a sandbox authenticate to external services without hardcoding credentials in source code, snapshots, or sandbox environment variables.

​
What is a Secret

A Secret is an encrypted credential managed within the scope of the current team. Novita uses the credential on eligible outbound HTTPS requests from a sandbox, but it never injects the real value into the sandbox itself. Instead, the sandbox environment variable holds an opaque placeholder rather than the actual API key. The outbound proxy substitutes the placeholder with the real value only when the target host matches the Secret’s allow list. This lets a sandbox reach credentials such as an LLM API key or a database password, while keeping the real value out of the sandbox’s environment variables, filesystem, and process arguments. Code running in the sandbox can use a Secret to access approved hosts, but it cannot read the real value through the Secret environment variable.
The real Secret value is never delivered into the sandbox. What the sandbox holds is an opaque placeholder; the substitution to the real value happens at the proxy layer, outside the sandbox.

​
How it works

In the normal Secret injection flow, the sandbox environment variable holds a placeholder, not the Secret’s real value. Novita uses an external proxy to replace eligible placeholders with the actual value at request time.
  1. You store a Secret value in the current team. Novita encrypts and stores it, and assigns an opaque placeholder such as novita_secret_<random_hex>, where <random_hex> is a randomly generated hexadecimal string.
  2. When you create a sandbox, you map an environment variable to a Secret using secret_envs. Novita sets the environment variable to the placeholder, not the actual value.
  3. When the sandbox makes an outbound HTTPS request, the proxy inspects it. If a request header carries the placeholder and the target host matches the Secret’s allow list, the proxy replaces the placeholder with the real value before the request reaches its destination.
  4. If the target host is not in the Secret’s allow list, the real value is not substituted. The placeholder is forwarded as-is through the sandbox’s normal outbound path, so the destination receives the placeholder rather than the real Secret.
Both request substitution and response filtering happen at the proxy layer, so the real Secret value is never injected into the sandbox through a Secret environment variable. For responses that match a Secret and use a supported format, the proxy also attempts to replace the real value back with the placeholder before returning the response to the sandbox.
Placeholders are only substituted in HTTPS request header values (for example Authorization or X-Api-Key). Request bodies, URL paths and query parameters, plain HTTP requests, and WebSocket message content are forwarded as-is and are not substituted. Prefer header-based authentication when using Secrets.
Last modified on August 5, 2026