Bindings

Bindings supply a runtime with what it needs at execution time: the upstream endpoints it may call and the variables and credentials it runs with.

A recipe describes your agent’s behavior, but it doesn’t hard-code where the model lives or which credentials to use. Bindings fill that gap with three concrete resource types: endpoints, variables, and write-only credentials. They are resolved when a task’s sandbox is materialized.

Scoping

Every binding is scoped, so the same project can give different runtimes different setups. A binding can apply to:

the whole project (when no narrower scope is set),
a runtime group: every runtime in that lineage,
a single runtime: one specific version, or
an environment lane: development, staging, or production.

These compose: a binding with no runtime or environment scope is available everywhere in the project, while a more specific scope narrows it down. A binding can be pinned to a runtime or a runtime group, but not both at once. When several rows apply, an exact environment beats a shared row, an exact runtime beats its runtime group, and a runtime-group row beats a project-wide row.

Scoping by environment is how you keep test and production setups apart: point a staging binding at a sandbox model gateway and a production one at the real thing, without touching the recipe.

Endpoints

An endpoint is an upstream target the agent is allowed to call: most often a model gateway, but also a plain HTTP API or an MCP server. Each endpoint names the host the agent may reach, what kind of target it is (llm, api, or mcp), and the headers the egress boundary should apply.

Header configuration may reference a write-only credential by name. References use ${NAME} and stay unresolved in operator-facing endpoint reads:


name: linear
url: https://mcp.example.com/mcp
kind: mcp
environment: production
headers:
  Authorization: "Bearer ${LINEAR_TOKEN}"

The endpoint response can show the configured template, header names, and referenced credential names, but never expands the credential’s secret. Use $$ when a literal dollar sign is required. If verify_path is configured, Introspection resolves the applicable credentials and checks the upstream before accepting the endpoint change.

Real header values never appear in what the sandbox sees. The agent learns which hosts and base URLs are available; the egress boundary applies the secret headers on the way out. That separation is a hard security boundary.

Variables

A variable is a sandbox environment variable made available to the runtime at execution time: the credentials and configuration your agent’s code reads from its environment. Variable names are normalized to the usual SERVICE_API_KEY shape.

A variable’s value comes from one of two sources, set by its kind:

value: a plain value you provide inline (for non-secret configuration).
credential: a secret, supplied out of band rather than stored as a plain value on the variable itself.

Like endpoints, variables are scoped by project, runtime group, runtime, and environment, so the same logical variable can resolve to different values per lane.

Credentials

A credential is a named, write-only secret used in endpoint header templates. Names are canonical environment-variable-style identifiers such as LINEAR_TOKEN. Create requires the secret; list and get return only has_secret and secret_set_at, and update replaces the secret wholesale.

Credentials use the same project, runtime-group, runtime, and environment scopes as endpoints. An endpoint may reference a credential only when that credential can apply everywhere the endpoint applies; otherwise the platform rejects the endpoint instead of leaving a production lane with an unresolved secret.


export LINEAR_TOKEN='...'
introspection bindings credentials create \
  --name LINEAR_TOKEN \
  --value-env LINEAR_TOKEN \
  --environment production

The CLI also accepts a mode-0600 file or stdin, so a secret never needs to appear in shell history. See CLI → Bindings.

At execution time

When a task starts, Introspection materializes its sandbox by resolving the applicable bindings for that runtime and environment. It injects variables into the sandbox environment, resolves credential references into endpoint headers at the trusted boundary, and tells the agent which hosts and base URLs it may reach. The recipe stays portable; the bindings make it runnable.

Runtimes: the deployable agent versions that bindings supply at execution time.
Environments: the development / staging / production lanes bindings can be scoped to.