Skip to main content
Let a local box call an authenticated HTTPS API without placing the real credential in its environment or files. Your host supplies a 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.
Save as llm_secret.py:
llm_secret.py
Expected output (the model’s wording can vary):
A successful authenticated model response demonstrates that the proxy injected a usable credential. The model key is supplied only to 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 in hosts, 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.
Use only the generated fake token with this echo service. Its response returns the token to the box. Never substitute a real credential here; do not assume upstream responses are scrubbed.
Save as secret_demo.py:
secret_demo.py
Expected output includes both 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 the maximum() 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)

In the Node SDK, 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 no SecurityOptions.minimum(); the weak-isolation preset is named development().
Resource limits set by 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.
  • hosts must match the actual outbound target host. For example, requesting api.openai.com with hosts=["openai.com"] does not match: use the exact host or the *.openai.com wildcard.
  • 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:
Once the interference is confirmed, return to 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/kvm accessible); WSL2 requires KVM enabled and the user in the kvm group.
  • 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).
A network hiccup during image pull also raises a RuntimeError, which can be caught and retried.

See also