Bindings

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 one exact runtime version or to the runtime itself, but not both at once.

When several rows apply, the most specific one wins:

Endpoints

An endpoint allows a runtime to contact one external HTTPS service. It can represent a plain HTTP API, a model gateway, or an MCP server. Start with the URL you would use to reach that service; the CLI turns it into the endpoint fields enforced by the egress boundary.

Create an API endpoint

Suppose the support-agent runtime needs to call https://api.example.com in development. Create the endpoint with the CLI:

introspection bindings endpoints create \
  --name orders-api \
  --kind api \
  --endpoint-url https://api.example.com \
  --runtime support-agent \
  --environment development

Here, --endpoint-url identifies the service, while --runtime and --environment determine where the binding applies. The CLI derives the allowed host, api.example.com, from the URL. An API endpoint permits HTTPS requests to that host; it does not restrict the runtime to one URL path.

Endpoint URLs must use a public DNS name. Do not use an IP address, a localhost name, embedded credentials, or a non-HTTPS public URL.

Verify the service before saving

Use --verify-path when Introspection should test the endpoint as part of the create or update:

introspection bindings endpoints create \
  --name orders-api \
  --kind api \
  --endpoint-url https://api.example.com \
  --verify-path /health \
  --runtime support-agent \
  --environment development

In this example, Introspection sends a blocking GET request to https://api.example.com/health. The endpoint is saved only if the service returns a 2xx response. The verification request includes any applicable credential-backed headers configured on the endpoint.

Changing the endpoint URL, headers, or verification path runs the check again. A rename or scope-only change does not. After a successful write, inspect the endpoint row for the same runtime and environment:

introspection bindings endpoints list \
  --runtime support-agent \
  --environment development

LLM and MCP connection URLs

The CLI accepts a complete HTTPS --endpoint-url for every endpoint kind and always derives its allowed host. For an API endpoint, only that host is needed. For an LLM SDK override or streamable HTTP MCP endpoint, Introspection also keeps the complete URL as the client connection base_url. MCP endpoints require that complete connection URL. An llm endpoint selects the upstream only for a bring-your-own-key runtime — see LLM providers for how llm_mode decides whether it applies.

For example, connect an MCP server at a particular path with:

introspection bindings mcp connect \
  --mcp-server-id linear \
  --name Linear \
  --endpoint-url https://mcp.example.com/mcp \
  --runtime support-agent \
  --environment development

The resulting endpoint permits the host mcp.example.com, and the MCP client connects to https://mcp.example.com/mcp. The host in a connection URL must be the same host the endpoint permits.

Use a file for longer configuration

Flags are convenient for a small endpoint. For headers or other longer configuration, put the same input in a YAML or JSON file. For example, save this as linear-endpoint.yaml. Header configuration can reference a write-only credential by name; ${NAME} remains a placeholder when you view the endpoint:

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

Pass the file to the endpoint command with @:

introspection bindings endpoints create @linear-endpoint.yaml

The url field is the file equivalent of --endpoint-url. The CLI derives the allowed host and, for this MCP endpoint, retains the complete URL as its base_url.

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.

Application identity and stored authorization

Stored headers and task identity assertions are separate authorization modes. A linked application places its short-lived identity assertion in the Authorization header at egress, so that endpoint cannot also configure a stored Authorization header. Other stored headers may be applied alongside the assertion. The receiving service must still authorize the asserted or attributed identity against its own resources; see Authentication & identity.

Variables

A variable is a sandbox environment variable made available to the runtime at execution time: plain configuration such as a region, feature flag, or service URL. Names use the familiar uppercase underscore form, such as SERVICE_REGION.

The value is always read from somewhere rather than typed on the command line: your shell (--from-env), a file (--from-file), or stdin (--from-stdin). create requires exactly one of the three; update accepts at most one, so an update that only changes the scope or the name passes none. For a secret, use a credential (below) referenced from an endpoint header instead — the value is applied at the egress boundary and never lands in the sandbox environment.

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. On update the secret is optional and replaces the stored one wholesale when supplied, so a metadata-only update leaves it untouched.

Credentials use the same project, runtime, runtime-version, 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.

Rotation is not revocation

Updating a credential takes effect immediately for sessions that start afterwards. Sessions that are already running resolved the old value into their session bundle, and converge on the new one only as their access token refreshes — bounded by roughly one access-token lifetime.

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

The CLI also accepts a mode-0600 file (--from-file) or stdin (--from-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.

Related concepts

• Runtimes: the deployable agent versions that bindings supply at execution time, and the development / staging / production lanes bindings can be scoped to.
• LLM providers: managed model access versus the BYOK path that llm endpoints serve.
• Security: the egress boundary that applies credentials outside the sandbox.