Skip to main content
Version: 0.9.19

Connector data in the sandbox

For an agent to work with your data, the code it runs in the sandbox needs a way to reach your databases, APIs, AWS resources, and external tools. AlphaAgent does this without ever embedding your credentials in compute configuration: credentials are resolved from your Secrets Manager at the moment the sandbox starts, handed to the code as environment variables, and — for AWS sources — replaced with short-lived temporary credentials. This page explains exactly how a connector's data becomes available inside a sandbox session, and why this design keeps secrets out of places they could leak.

The principle: credentials resolved at invocation, never baked in​

Connectors (your configured data sources — SQL, REST, MCP, Snowflake, and AWS) are defined in Studio, and their credentials are stored in Secrets Manager in your account. Agents never receive raw credentials directly from the UI. Instead, when a sandbox session is created for a conversation, AlphaAgent looks up the connectors that agent is allowed to use, fetches a fresh credential bundle, and makes it available to the sandbox.

Crucially, those credentials are not stored in the Lambda function's configuration. They are fetched at invocation time, so inspecting a function's configuration reveals nothing sensitive. The end-user view of connectors is in Data connectors.

How an agent reaches your data: CONN_* environment variables​

When a sandbox session starts, each connector the agent is authorized to use is flattened into environment variables that the agent's code can read. The naming pattern is:

CONN_{connector_id}_{KEY}

For example, a SQL connector's host, database name, and credentials each surface as a separate CONN_{id}_* variable. The agent is told, in its instructions, that these variables exist and how to use them — so it reaches your data by running code that reads the variables, rather than by ever seeing a credential printed in the conversation.

MCP connectors (external tool servers) additionally receive the server URL and request headers as CONN_{id}_MCP_SERVER_URL and CONN_{id}_MCP_HEADERS, and the base sandbox image includes a client library so the code can connect to that MCP server directly.

Permission is checked before credentials are issued​

A connector's credentials are only ever provided for an agent that is actually assigned that connector. When the sandbox is provisioned, the request carries the agent's identity, and AlphaAgent validates that the agent is permitted to use each requested connector before any credential bundle is returned. An agent cannot obtain credentials for a connector it was not given.

Connector versions can also be pinned for a conversation, so a long-running conversation keeps using the connector configuration it started with even if the owner publishes a new version mid-session.

AWS connectors get short-lived credentials​

AWS connectors never hand the sandbox a stored, long-lived secret. Instead, AlphaAgent assumes the role you configured in your account (using a role ARN and a unique external id that ties the trust relationship to your deployment) and mints short-lived temporary credentials with a bounded lifetime. Those temporary credentials are what land in the sandbox.

This has two effects: the credentials in the sandbox expire on their own, and what the agent can do is exactly what your IAM policy on that role allows — nothing more. AWS connectors are sandbox-only: they are consumed by the code interpreter, not proxied through any other path.

How the secret reaches the running code​

There is one more layer that keeps plaintext secrets out of function configuration. When code actually executes, the environment Lambda fetches the connector secret from Secrets Manager at that moment and injects the CONN_* variables before the user code runs. The secret is never written into the function's static configuration, so a snapshot of the function reveals nothing.

Why this matters for a security review​

  • No standing credentials in compute. Inspecting the execution function's configuration never exposes a connector secret.
  • Least privilege for AWS. AWS access is scoped by your own IAM role and expires automatically because it is delivered as short-lived temporary credentials.
  • Server-mediated for the rest. For MCP and other external services, the credentials and connection details are supplied to the sandbox rather than exposed to the model in conversation, and the agent only ever holds them for the life of the session.
  • Stays in your account. All of this happens inside your AWS account; connector data does not transit PrometheusRL.

Where to go next​