Secret; BoxLite’s outbound proxy inserts its value into configured request headers for allowed hosts.
For remotely hosted boxes, use Cloud Secrets. The examples below run a local VM and require a supported machine with hardware virtualization. They do not require a Cloud API key.
Make your first LLM call
Run one inference request inside a box. Your workstation supplies the real model key to BoxLite; the code inside the box sends only<BOXLITE_SECRET:model> and receives the model’s reply.
You need an OpenAI API key with access to gpt-4.1-mini. Run the commands on your workstation. The examples create a disposable box, print the reply, and remove the box automatically.
Using another OpenAI-compatible provider? Change api.openai.com in both the Secret host and request URL, and change the model ID. Use that provider’s key. The real key still belongs only in the Secret configuration.
- Python
- TypeScript
- CLI + REST
llm_secret.py:llm_secret.py
Secret.value; it is not passed to the guest command or guest environment.
Connect your own API
Keep the credential on the trusted host. Configure the API hostname inhosts, its authentication header in headers, and the real credential in value. Set the application’s API key inside the box to a dummy value such as <BOXLITE_SECRET:model>.
The Secret configuration is the same for local and Cloud runtimes. See provider configuration examples in all three formats and authentication header formats. Continue using the local runtime shown above.
The proxy replaces only configured headers already present in the request. Missing headers are not added. The placeholder is a dummy value, not an authorization boundary: code inside the box can exercise the credential’s permissions at allowed hosts.
For verification with a real credential, call an authenticated endpoint on its provider and check the expected result. Do not use an echo endpoint. To limit destinations as well as credential injection, configure outbound network access.
Optional: verify injection with a fake token
Use this diagnostic when you want to check the mechanism without a provider account. It verifies both the guest environment and the header received by the upstream.Run the fake-token diagnostic
Run the fake-token diagnostic
- Python
- TypeScript
- CLI + REST
secret_demo.py:secret_demo.py
PASS checks and Removed the test box.Troubleshooting
Secret injection and OS-level sandbox hardening are independent. Configure both when running untrusted workloads.
Tighten isolation (SecurityOptions)
For untrusted workloads, use themaximum() preset to enable all isolation. Note: security must be passed through advanced=AdvancedBoxOptions(...); there is no top-level security= keyword, and AdvancedBoxOptions is exported only under the boxlite.boxlite submodule.
Combining the two (credentials plus isolation)
secrets and security are both direct fields of SimpleBoxOptions (there is no advanced wrapper layer), and SecurityOptions is expressed as a plain object (there is no maximum() static preset).
Parameters and Returns
Secret(name, value, hosts=[], placeholder=None)
Constructor signature: see sdks/python/src/options.rs.
Injection entry point:
BoxOptions(secrets=[Secret(...)]), or passed through via SimpleBox(..., secrets=[...]). Node uses { name, value, hosts?, placeholder? }.
SecurityOptions (Python)
Preset static methods (sdks/python/src/advanced_options.rs):
Note: there is noResource limits set bySecurityOptions.minimum(); the weak-isolation preset is nameddevelopment().
maximum(): max_open_files=1024, max_file_size=1 GiB, max_processes=100 (max_memory/max_cpu_time are left to the VM configuration).
Custom constructor parameters (defaults per the source signature):
Attaching SecurityOptions to a box
AdvancedBoxOptions(security=None, health_check=None): exported only under the boxlite.boxlite submodule; import boxlite; boxlite.AdvancedBoxOptions at the top level is not available.
box.exec(...) return value (ExecResult)
Troubleshooting
AttributeError: module 'boxlite' has no attribute 'AdvancedBoxOptions'
AdvancedBoxOptions lives in the boxlite.boxlite submodule, not the top level.
AttributeError: type object 'SecurityOptions' has no attribute 'minimum'
There is no minimum() preset. Use SecurityOptions.development() for weak isolation, and standard() / maximum() otherwise.
Passing security= at the top level errors out
BoxOptions / SimpleBox do not have a security= keyword. Security options must be wrapped in advanced=AdvancedBoxOptions(security=...). Passing security= directly reports a TypeError due to the unknown keyword argument.
The secret was not injected (the request still contains the raw placeholder / authentication fails)
- The proxy substitutes placeholders in request headers (typically
Authorization), the URL query string, and the request body. It does not touch the URL path — a placeholder there is forwarded literally. hostsmust match the actual outbound target host. For example, requestingapi.openai.comwithhosts=["openai.com"]does not match: use the exact host or the*.openai.comwildcard.- Egress must be HTTPS and pass through the BoxLite proxy; if the sandbox network is fully disabled, injection cannot occur.
seccomp / jailer behave differently on macOS
seccomp_enabled, new_pid_ns, new_net_ns, and chroot are Linux-only. Setting them on macOS does not error — the runtime logs a warn and ignores them. seccomp_enabled takes effect only on Linux (standard()/maximum() already guard it internally with cfg!(target_os = "linux")). On macOS, even setting it to True does not enable seccomp; this is a platform difference. The jailer is available on both Linux and macOS.
Isolation is blocking your program and you cannot tell which layer
Downgrade temporarily to confirm it, then put it back — do not ship with isolation off:standard() or maximum() and narrow the specific
field instead. Which field touches which layer is on
Security and isolation.
The box fails to start (RuntimeError) — virtualization unavailable
BoxLite depends on hardware virtualization:
- Linux: requires KVM (
/dev/kvmaccessible); WSL2 requires KVM enabled and the user in thekvmgroup. - macOS: uses Apple’s Hypervisor.framework and does not need
/dev/kvm. - Without virtualization support, the box fails to start and raises a standard
RuntimeError(the process stays alive and can be caught with try/except).
RuntimeError, which can be caught and retried.
See also
- Box types — Box types and lifecycle
- Compute resources — CPU / memory / disk resource configuration

