<BOXLITE_SECRET:model>. You choose which destination hosts and headers receive the real value.
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 and a BoxLite Cloud API key. 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 and paste your BoxLite Cloud API key, then your OpenAI API key, at the prompts:llm_secret.py
Secret.value; it is not passed to the guest command or guest environment.
How it works
A Secret is configured on a box throughBoxOptions.secrets. This guide does not require a separate secret-store setup or a public tunnel.
A Secret controls where a credential is injected. It does not restrict all outbound traffic. Use network policy if you also need to limit which destinations the box can reach.
Connect your own API
Once the demo works, configure your production box with the API’s real hostname, credential, and authentication header. Read the real credential on your workstation or trusted backend:- Python
- TypeScript
- CLI + REST
api.your-provider.com with the hostname from your API URL, without https:// or a path. Pass secrets=[provider_secret] in the BoxOptions used to create your box.
Inside the box, configure your HTTP client or agent with the placeholder <BOXLITE_SECRET:model>, not the real key. For example, the request should contain:
OPENAI_API_KEY, set that variable to the placeholder through the box environment configuration:
Python uses env=[("OPENAI_API_KEY", "<BOXLITE_SECRET:model>")]; TypeScript uses env: [{ key: "OPENAI_API_KEY", value: "<BOXLITE_SECRET:model>" }]; the REST create body uses "env": {"OPENAI_API_KEY": "<BOXLITE_SECRET:model>"}. Keep the Secret configuration alongside it.
Configure the agent’s API base URL separately. It must use the hostname you listed in hosts.
Validate with a read-only endpoint on the real provider that requires authentication. Check for its expected successful response; do not print authorization headers or full debug request logs.
Choose the authentication header
Use the header required by your API:{value} is the proxy’s template variable. <BOXLITE_SECRET:model> is the dummy value used by your application. They have different roles; keep the real credential only in Secret.value.
The request must already contain the configured header. BoxLite replaces its value when the host matches, even if the original value is empty or differs from the placeholder. It does not add a missing header. Other headers remain unchanged.
This is header injection, not a general search-and-replace operation over URLs, query strings, or request bodies. It is intended for authenticated HTTPS APIs, not credentials needed by a process locally.
Restart, replace, or retire a credential
A box retains its Secret configuration across a stop/start. You do not need to pass the key again each time you resume it. To adopt a new credential using the workflow in this guide, create a replacement box with the updated Secret, verify authentication, then move work to it. Changing a local Python variable does not update a box that already exists. Remove a box when you no longer need it. Deleting the box does not revoke the credential at its provider; revoke the provider key separately when retiring it. For agents with a public service, you can move a fixed domain to the replacement box.Security boundaries
- Keep real keys out of
BoxOptions.env, images, uploaded files, agent prompts, and commands executed inside the box. - Use the narrowest destination hosts and provider permissions your application needs. Code in the box can use the credential’s authority at those hosts.
- A trusted destination receives the real credential. If it reflects the value in its response, code in the box can read that response.
- Keep TLS verification enabled. With a custom image or HTTP library, ensure it trusts the box’s proxy CA through the system CA bundle.
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 and paste your BoxLite Cloud API key when prompted:secret_demo.py
PASS checks and Removed the test box.Troubleshooting
Next steps
Deploy an agent
Configure your agent’s provider key as a placeholder and run real tasks.
Control outbound access
Restrict where your box can connect, independently of Secret injection.

