# Sandbox security architecture

Understand sealed secrets, managed HTTPS inspection, destination policy, and fail-closed sandbox egress.

Salambo lets sandbox code call approved external services without placing plaintext sandbox-scoped secrets in the sandbox environment.

The security boundary combines:

* a run-bound network policy;
* short-lived sandbox authentication;
* sealed secret placeholders;
* destination allowlists;
* managed HTTPS inspection;
* fail-closed validation at the outbound proxy.

## Request flow

```mermaid
sequenceDiagram
  participant Builder
  participant Runtime as Trusted hosted runtime
  participant Sandbox
  participant Proxy as Managed outbound proxy
  participant API as Allowed external API

  Builder->>Runtime: Declare secret and allowedHosts
  Runtime->>Runtime: Encrypt secret at rest
  Runtime->>Runtime: Mint run-bound sealed placeholder
  Runtime->>Sandbox: Project placeholder, proxy session and trusted CA
  Sandbox->>Proxy: HTTPS request with placeholder in a header
  Proxy->>Proxy: Validate session, run policy, destination and expiry
  Proxy->>Proxy: Open placeholder and substitute secret
  Proxy->>API: Re-encrypted HTTPS request with plaintext header
  API-->>Proxy: HTTPS response
  Proxy-->>Sandbox: Response
```

## Sealed secret minting

For a secret exposed to the sandbox, Salambo creates a short-lived sealed placeholder when it prepares the run. The authenticated payload binds together:

* the secret value and name;
* the allowed destination hosts;
* the active run session;
* issue and expiry times.

The sandbox receives the placeholder, not the plaintext value. The key needed to open it remains outside the sandbox. Copying the placeholder to another run, waiting past expiry, modifying it, or sending it to a different host causes the request to fail.

Runtime-only provider credentials are not projected into the sandbox at all.

## Why the proxy is in the middle

HTTPS normally hides request headers from network policy. Salambo therefore routes managed sandbox HTTPS through an authenticated proxy and gives the managed sandbox a Salambo certificate authority to trust.

For an allowed destination, the proxy presents a destination-specific certificate to the sandbox, opens the inspected HTTPS request, applies policy and secret substitution, then creates a separate encrypted TLS connection to the external service.

This controlled TLS inspection allows Salambo to:

* verify the real destination before releasing a secret;
* replace a sealed placeholder only in a supported request header;
* keep plaintext credentials out of sandbox environment variables;
* block private, loopback, link-local, and cloud-metadata destinations;
* record allow/deny decisions without recording secret values.

The managed CA is part of the sandbox runtime. Builders do not configure its certificate or private key.

## Destination enforcement

Two checks must pass:

1. The run's egress policy must allow the destination.
2. Every substituted secret must independently allow that destination through `allowedHosts`.

The secret-specific rule cannot broaden the run policy. A request is denied when the session is missing, expired, stopped, or belongs to another sandbox; when the destination is disallowed; or when the sealed placeholder is invalid, expired, or scoped to another host.

## Supported secret use

Secret substitution works in HTTP request headers when the header value is either:

`SEALED_PLACEHOLDER` below is notation for the opaque value Salambo writes into your declared environment variable, not a literal string. For a secret named `MY_API_KEY`, read `process.env.MY_API_KEY` and use that value directly in the header.

```text
SEALED_PLACEHOLDER
```

or:

```text
Bearer SEALED_PLACEHOLDER
```

This matches common API-key and bearer-token SDK behavior. Salambo does not substitute secrets in URLs, query parameters, request bodies, host headers, or proxy transport headers.

If an integration requires a secret in an unsupported location, keep the credential in the trusted runtime or use a different integration design. Do not expose a plaintext workaround to the sandbox.

## Failure model

The boundary fails closed. A denied request does not fall back to direct network access or plaintext secret injection.

Use the run's Activity and Diagnostics views to distinguish:

* destination denied by egress policy;
* missing secret host scope;
* secret denied for the destination;
* expired or invalid sandbox session;
* expired or invalid sealed secret;
* upstream connection failure.

Continue with [environment variables and secrets](/docs/deploy/environment-secrets) to declare a sandbox secret and [networking and regions](/docs/deploy/networking-regions) to configure run-level egress.