Using secrets
Give your sandbox the credentials it needs through requests, environment variables, or files.
Save a workspace secret before using these examples. The examples use a GitHub personal access token saved as GITHUB_TOKEN.
Choose the option that fits your app:
- Transparent injection replaces a placeholder in outgoing HTTPS requests, outside the sandbox.
- Files put the real value in a file the app can read.
Use SDK version 1.4.0 or later for the SDK examples. Your API key needs Secrets access. Transparent injection also requires an image with the managed HTTPS trust.
Call an API with transparent injection
Create the github request policy first. It allows GITHUB_TOKEN in the Authorization header of GitHub user requests. Select it when creating the sandbox:
luxor sandbox create --secret-policy githubThe new sandbox becomes your active session. Run:
luxor sandbox exec -- curl -fsS \
-H 'Authorization: Bearer secrets://GITHUB_TOKEN' \
https://api.github.com/userGitHub returns the account associated with your token. Inside the sandbox, the command contains only the placeholder. We substitute the token before forwarding the matching request to GitHub.
Luxor Agent Cloud does not add Bearer. Your application supplies the header format the API expects. For example, Bearer secrets://GITHUB_TOKEN becomes Bearer YOUR_TOKEN. For an API that expects a raw key in X-API-Key, send just the placeholder in that header and allow X-API-Key in the policy.
When finished with this sandbox:
luxor sandbox terminateKeep the secret and policy to reuse them in the next sandbox.
Set a placeholder once
If an application reads its credential from an environment variable, set that variable when creating the sandbox:
luxor sandbox create --secret-policy github \
--env GITHUB_TOKEN=secrets://GITHUB_TOKENLater commands inherit this environment variable. Its value is the literal placeholder. Luxor Agent Cloud substitutes it only when the application sends it in a request that matches a selected policy.
For a single command, use env:
luxor sandbox exec -- env GITHUB_TOKEN=secrets://GITHUB_TOKEN your-commandReplace your-command with the application you want to run. sandbox exec -- executes a program directly, so a leading GITHUB_TOKEN=... without env is not a shell assignment.
Select more than one policy
Pass saved policy names separated by commas. Both policies must already exist in your workspace:
luxor sandbox create --secret-policy github,internal-apiYou can also repeat --secret-policy. Permissions from the selected policies are combined. A matching rule from any selected policy can authorize a request.
Policies control secret substitution. They do not restrict all network traffic. Ordinary requests still follow the sandbox's network settings, and a policy does not override a network restriction.
Transparent injection from an SDK
These examples use the same GITHUB_TOKEN secret and github policy. Install your SDK and configure TENKI_API_KEY as described in the quickstart. Use a key for the workspace containing the secret and policy.
import { stdoutText, TenkiSandbox } from "@tenkicloud/sandbox";
const client = new TenkiSandbox();
await using session = await client.createAndWait({
secretPolicies: ["github"],
});
const result = await session.exec("curl", {
args: ["-fsS", "-H", "Authorization: Bearer secrets://GITHUB_TOKEN", "https://api.github.com/user"],
});
console.log(stdoutText(result));Each example closes its sandbox when it leaves scope. To set placeholders in the session environment, use TypeScript's env, Python's env, or Go's WithEnvs option when creating the sandbox.
Deliver a secret file
Use a file when your application reads credentials from disk. We deliver it at the path you choose inside the sandbox.
This example uses a Node.js app that reads GITHUB_TOKEN from .env. Replace https://github.com/your-org/your-app.git with your public repository. It should have a package-lock.json and an npm run dev script that loads .env.
Create a local .env.example using the GITHUB_TOKEN secret saved earlier:
GITHUB_TOKEN=secrets://GITHUB_TOKENCreate a sandbox with the secret file, clone your app, and start it:
luxor sandbox create --secret-file ./.env.example:/app/.env
luxor sandbox exec -- git clone https://github.com/your-org/your-app.git /app/web
luxor sandbox exec --stream -- bash -c \
'cd /app/web && cp /app/.env .env && npm ci && npm run dev'Luxor Agent Cloud writes the real token into /app/.env. The command copies it into the cloned app's directory before starting the dev server. Your local .env.example still contains only the placeholder. No request policy is needed.
The dev server runs in the foreground. When finished, terminate the sandbox from another terminal:
luxor sandbox terminateYou can repeat --secret-file for multiple files. Destinations must be below /app/, /workspace/, or /home/tenki/. Luxor Agent Cloud creates files with owner-only read/write permissions, 0600.
Replacement is plain text: Luxor Agent Cloud does not escape values for JSON, YAML, or shell syntax.
Secret files from an SDK
To use a .env.example already in your repository, see Using secrets with templates.
Declare the .env contents when creating the sandbox, then clone the app, copy in .env, install dependencies, and run the dev server. Use your own repository URL, with the same requirements as above. The SDK call waits while the server runs; the sandbox closes when the example exits normally.
import { stdoutText, TenkiSandbox } from "@tenkicloud/sandbox";
const client = new TenkiSandbox();
await using session = await client.createAndWait({
secretFiles: [{ path: "/app/.env", content: "GITHUB_TOKEN=secrets://GITHUB_TOKEN\n" }],
});
await session.git.clone("https://github.com/your-org/your-app.git", { directory: "/app/web" });
const result = await session.exec("bash", {
args: ["-c", "cp /app/.env .env && npm ci && npm run dev"],
cwd: "/app/web",
});
if (result.exitCode !== 0) throw new Error("App failed");
console.log(stdoutText(result));Reuse an app with another secret
Keep the same .env.example file while choosing a different GitHub token at launch:
luxor sandbox create --secret-file ./.env.example:/app/.env \
--secret-override GITHUB_TOKEN=STAGING_GITHUB_TOKENBoth names refer to workspace secrets; create STAGING_GITHUB_TOKEN first. Overrides apply to environment and file references, not transparent injection policies.
Rotation, revocation, and pause/resume
Files and process memory can be retained in snapshots, including copies your app makes. Treat snapshots and images created from a sandbox with delivered secrets as containing those secrets. Revoking a secret in Luxor Agent Cloud does not erase existing copies or revoke the credential at its provider.
Secrets and snapshots
With the luxor CLI 2.11.0 or later, luxor sandbox snapshot get and snapshot list show whether a snapshot was taken from a sandbox with secrets (has_runtime_secrets, and the SECRETS column in the list).
Restoring such a snapshot requires workspace edit permission, or an API key with Secrets access.
A restore delivers the current secret versions, not the values the snapshot had. If you rotated a secret after the snapshot, the restored sandbox gets the new value. Luxor Agent Cloud restarts the sandbox's managed runtime so it starts on those versions.
A secret you deleted after the snapshot is skipped.
The restore still succeeds, and returns a RESTORE_SECRETS_SKIPPED warning that names the missing secrets:
restored without workspace secrets that no longer exist: STAGING_GITHUB_TOKENluxor sandbox create --snapshot shows it on a warning line, and in warnings with --json.
The SDKs print it to stderr by default, as tenki sandbox warning [RESTORE_SECRETS_SKIPPED]: ..., and return it in warnings on the session (Warnings in Go).
SDK releases up to 1.4.4 report the code as UNSPECIFIED, with the same message.
If all of the snapshot's secrets are gone, the restore fails instead of starting the sandbox with the deleted values.
The same warning also appears when a secret environment variable is skipped because a platform or template default now sets that variable, and when the snapshot's source sandbox had no secret bindings to deliver again.
If a sandbox is rebooted because its guest agent stopped answering, its secrets are delivered again and its managed runtime restarts.
Troubleshooting
If access is denied, check that your account can edit the workspace and your API key has Allow Secrets access. If the app cannot find an environment variable, check that its dev script loads the .env file copied into /app/web.
An allowed destination receives the real credential. Choose destinations you trust and keep both provider permissions and policy rules limited to what the sandbox needs. Transparent injection keeps the credential out of the guest's request construction; it cannot prevent an allowed service from returning it in a response.