Access, secrets, and usage

Keep account API keys on your server. Use scoped tokens when a browser needs access to a sandbox.

Resources and usage

Read the serving deployment’s resource sizes, environments, harnesses, and your account’s usage before creating workloads.

import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
if (!apiKey) throw new Error("Set TANGLE_API_KEY");

const client = new Sandbox({
  apiKey,
  baseUrl: "https://sandbox.tangle.tools",
});

const [shapes, environments, backends, usage, subscription] = await Promise.all([
  client.shapes(),
  client.environments.list(),
  client.listBackends(),
  client.usage(),
  client.subscription(),
]);
console.log({ shapes, environments, backends, usage, subscription });

client.shapes() returns named sizes and the account’s resource ceiling. box.resources reports a sandbox’s granted size. box.resourceUsage() reads its current CPU and memory counters. box.capabilities() reports features supported by that running sandbox image.

Use fleet usage and GPU lease charges for those resources.

Inject a secret

Set SERVICE_TOKEN locally to the secret your workload needs. This example creates a uniquely named secret, injects only that secret, checks its presence, and removes its test resources.

import { Sandbox } from "@tangle-network/sandbox";

const apiKey = process.env.TANGLE_API_KEY;
if (!apiKey) throw new Error("Set TANGLE_API_KEY");

const client = new Sandbox({
  apiKey,
  baseUrl: "https://sandbox.tangle.tools",
});

const serviceToken = process.env.SERVICE_TOKEN;
if (!serviceToken) throw new Error("Set SERVICE_TOKEN");
const secretName = "DOCS_" + crypto.randomUUID().toUpperCase().replaceAll("-", "_");
await client.secrets.create(secretName, serviceToken);
const box = await client.create({
  maxLifetimeSeconds: 900,
  secrets: [secretName],
});
await box.waitFor("running");
const result = await box.exec('test -n "$' + secretName + '"');
console.log(result.exitCode === 0 ? "Secret available" : "Secret missing");
await box.delete();
await client.secrets.delete(secretName);

For existing secrets, pass their names in client.create({ secrets: [...] }). Avoid secrets: "all" when a workload only needs specific credentials. box.setRuntimeEnv() updates application variables for new processes; it does not change saved creation settings.

Browser access

Authenticate the user on your server and verify ownership of the sandbox and session before issuing a token. Call box.mintScopedToken() with the scope for the intended client.

Runtime clients use sidecarProxyUrl and token from the response. Session tokens require both the browser sessionId and the actual runtimeSessionId. Refresh expiring tokens through the authenticated backend. Never send the account API key or box.connection.authToken to browser code.

Teams

client.teams manages teams, invitations, member roles, team secrets, and templates. Pass a team’s ID to client.create({ teamId }) to create a sandbox for its members. An invitation grants access only after the recipient accepts it.

Confidential compute

createConfidentialSandbox() provisions through a compatible Tangle confidential operator. box.getTeeAttestation() and box.getTeePublicKey() retrieve its hardware evidence and encryption key. Verify attestation before sending sealed secrets. These calls require a confidential-compute deployment; ordinary hosted sandboxes do not imply TEE support.