Environment service reference

Choose services from the dependencies your agent actually calls. Interceptor starts them inside the synthetic environment and records the supported interactions. This reference covers all four managed services[].kind values and the related network, identity, filesystem, capture, and provider facilities.

Examples are fragments for a complete environment blueprint. Place referenced assets inside that directory, validate and seal it, rebuild its wrapper, and exercise the application path that uses each configured service.

Service inventory

Kind Use for Configuration assets
fixture_http Fixed HTTP responses matched to declared requests. fixtures YAML.
stateful_http JSON records with declared read/write HTTP routes. seed JSON and routes YAML.
mcp_http Simulated non-streaming MCP tools with fixed or stateful behavior. tools YAML; seed JSON for stateful tools.
postgresql Native PostgreSQL/pgvector accessed through the agent's ordinary driver. Ordered postgresql.schema and postgresql.seeds SQL assets.

Only the generic MCP implementation is available. These kinds do not automatically model every API of a named third-party service.

Common service fields

Field Type and requirement Meaning/default
id Required unique lowercase identifier. Used by credentials, policies, and evidence references.
kind Required string from the inventory above. Selects the handler.
listen Required unique loopback host:port string. Internal listener; choose a port not used elsewhere in the blueprint.
hostnames Required nonempty array of unique hostnames containing a dot. Names resolved inside the target, not public DNS records.
authorization Optional object for HTTP/MCP kinds. Synthetic issuer/audience/scope policy; absent means no bearer requirement.
injections.create_collections Optional array for stateful HTTP/MCP collections. Explicit bounded creation permission; absent means no such permission.
export_contracts Optional boolean, default false; v1alpha2. Export reviewed endpoint/tool descriptions and schemas.
implementation Optional string for MCP, generic only; v1alpha2. Defaults to generic behavior.
options Reserved for managed HTTP/MCP services. No implemented general-purpose behavior; omit. Rejected for PostgreSQL.

Use only kind-specific fields that belong to the chosen service. PostgreSQL rejects HTTP/MCP authorization, fixture, route, tool, endpoint, and generic seed/options fields; its own nested configuration supplies database authentication and state.

For HTTP/MCP synthetic bearer authentication:

authorization:
  issuer: sandbox-identity
  audience: http://tickets.sandbox.test:18100
  required_scopes: [tickets:read]
  allow_delegated: true

issuer and audience are required strings. required_scopes is an optional string array; allow_delegated defaults false. Referenced issuers, grants, scopes, and delegations must agree. Authorization is service-wide, not per route/tool.

Optional creation policy syntax:

injections:
  create_collections:
    - collection: tickets
      max_resources: 100

Each entry requires a collection name and integer bound from 1 through 100000. A compatible sealed create route/tool must already exist. This declares capability and bounds; it does not choose campaign scenarios or grant Operator permissions.

Fixed HTTP responses

Use fixture_http for a dependency that does not need mutable records. Its required fixtures string names a YAML asset relative to the blueprint directory.

services:
  - id: directory
    kind: fixture_http
    listen: 127.0.0.1:18110
    hostnames: [directory.sandbox.test]
    fixtures: assets/directory.yaml

assets/directory.yaml:

rules:
  - id: find-contact
    priority: 100
    match:
      method: GET
      path: /contacts
      query: {id: contact-001}
      headers: {Accept: application/json}
    response:
      status: 200
      headers: {Content-Type: application/json}
      json: {id: contact-001, name: Example Contact}

Each rule has an ID, numeric priority, request match, and response. Match method/path and optionally selected query, header, and JSON values. Higher priorities win; overlapping matches at equal priority fail validation. A response supplies HTTP status, optional headers, and at most one of json, string body, or asset. The latter names a body file relative to the blueprint root.

Configure the application to request http://directory.sandbox.test:18110/contacts?id=contact-001. Request bodies are bounded to 1 MiB. No match returns 501 and records a coverage gap rather than an invented response. Fixtures remain sealed; snapshots reuse their definitions. Check matching and nonmatching requests and inspect the recorded service observations.

Stateful HTTP records

stateful_http requires seed and routes asset paths:

services:
  - id: tickets
    kind: stateful_http
    listen: 127.0.0.1:18100
    hostnames: [tickets.sandbox.test]
    seed: assets/tickets.json
    routes: assets/ticket-routes.yaml

The JSON seed maps collection names to keyed records:

{"tickets":{"ticket-001":{"id":"ticket-001","status":"open"}}}

The routes asset declares methods, paths, actions, and collections:

routes:
  - id: list-tickets
    method: GET
    path: /tickets
    action: list
    collection: tickets
  - id: get-ticket
    method: GET
    path: /tickets/{id}
    action: get
    collection: tickets
  - id: create-ticket
    method: POST
    path: /tickets
    action: create
    collection: tickets
    key_field: id
  - id: patch-ticket
    method: PATCH
    path: /tickets/{id}
    action: patch
    collection: tickets
    patch_fields: [status]
Action Additional configuration
list Collection only; no key placeholder.
get, replace, delete One {...} path placeholder identifying the record.
create key_field string and no path placeholder.
patch Key placeholder and explicit string array patch_fields.

Configure the agent's base URL to http://tickets.sandbox.test:18100. Undeclared routes return 501 with a coverage gap. Successful mutations are journaled before application; snapshots reconstruct records from sealed seeds and journal state. Verify a read/write/read sequence and, if you claim restoration, its restored result.

MCP tools

mcp_http requires a clean absolute endpoint path and a tools YAML asset. seed is required when any tool uses stateful behavior and omitted for fixtures only.

services:
  - id: knowledge
    kind: mcp_http
    listen: 127.0.0.1:18200
    hostnames: [knowledge.sandbox.test]
    endpoint: /mcp
    tools: assets/knowledge-tools.yaml

Minimal tools asset:

tools:
  - name: get_document
    description: Read a synthetic document by its identifier.
    input_schema:
      type: object
      properties:
        id: {type: string}
      required: [id]
      additionalProperties: false
    behavior:
      kind: fixture
      fixtures:
        - id: document-001
          priority: 100
          match: {id: document-001}
          result:
            content:
              - type: text
                text: This is a synthetic reference document.

Configure the MCP client for http://knowledge.sandbox.test:18200/mcp. Tool names are unique and contain 1–128 letters, digits, dots, underscores, or hyphens. Description and object-shaped input_schema are required. title and output_schema are optional. The runtime checks required top-level arguments, basic types, and additionalProperties: false; it does not execute full JSON Schema validation or prove result conformance to the declared output schema.

Fixture match is a subset of arguments. Higher priorities win; ambiguous equal priorities fail validation. Results support text content, optional structured_content, and optional is_error. No matching fixture returns a tool error and coverage gap. Requests, individual seed records, and encoded results are bounded to 1 MiB.

For mutable tools, set behavior.kind: stateful and use the same collection/key JSON seed layout as stateful HTTP:

Action Required behavior fields
list collection
get, replace, delete collection, key_argument
create collection, key_field
patch collection, key_argument, patch_fields

With v1alpha2, optional tool contract_basis is synthetic by default or a reviewed provider-declared, source-derived, or observed basis. delivery_examples hold public id/input/output examples; output schemas describe structured content. Do not export private fixture bodies as public contract examples.

Supported operations are individual non-streaming JSON-RPC POST requests for initialize, ping, tools/list, tools/call, and notifications/initialized. The service does not forward to a real MCP server or run arbitrary fixture code. Streaming/SSE, batch requests, pagination, resources/prompts, server-initiated requests, and interactive OAuth are outside this subset. Unknown methods/tools fail explicitly. Test initialize/list/call with the agent's real client.

Evidence records discovery, calls, results, errors, and state changes. Stateful records restore through the state journal; protocol connections and in-flight calls do not. See the selected release's MCP detail for protocol negotiation and contract-export limits.

Managed PostgreSQL and pgvector

Interceptor packages the managed database into the application wrapper. The target uses its normal PostgreSQL driver and connection pool. There is no host database, separate database container, or runtime database download to operate.

network:
  dns: {enabled: true}
  tls: {enabled: true, trust_mode: auto}
services:
  - id: database
    kind: postgresql
    listen: 127.0.0.1:15432
    hostnames: [database.sandbox.test]
    postgresql:
      database: support
      roles:
        - {name: agent, password: synthetic-password}
      schema: [assets/schema.sql]
      seeds: [assets/seed.sql]
      tables:
        - id: documents
          schema: public
          name: documents
          keys: [id]
          fields: [body]

For this minimal service example, schema.sql can contain:

CREATE TABLE public.documents (id text PRIMARY KEY, body text NOT NULL);
GRANT USAGE ON SCHEMA public TO agent;
GRANT SELECT ON public.documents TO agent;

And seed.sql:

INSERT INTO public.documents VALUES ('document-001', 'Synthetic reference text');

Use the actual application migrations and populated records for real onboarding. The support recipe includes customer/order relationships and compatible document embeddings.

Database fields and bounds

All fields below are inside postgresql:

Field Requirement/type Default or bounds
database Required SQL identifier string. No reserved postgres, pg_, or template database name.
roles Required array of {name, password}. 1–16 roles; synthetic passwords 8–256 bytes.
schema Required nonempty ordered string array of SQL assets. Schema and seed files together: at most 128.
seeds Ordered string array of SQL assets. Populate the initial database after schema creation.
tables Optional array of exposed table policies. Omit to expose no table-mutation policy.
max_connections Integer. 16; allowed 1–128.
query_timeout_ms Integer milliseconds. 30000; allowed 100–120000.
max_result_bytes Integer bytes. 8388608; allowed 1024–67108864.
max_storage_bytes Integer bytes. 268435456; allowed 33554432–10737418240.

SQL identifiers use ASCII letters/digits/underscores, start with a letter or underscore, and are at most 63 characters. Application roles cannot use reserved postgres, pg_, or interceptor_ names. They cannot be superusers, create roles/databases, replicate, bypass row-level security, or hold other roles.

Each table policy requires unique id, schema, name, keys (1–8 column names), and fields (1–64 writable columns). Key columns cannot also be writable fields. Optional allow_create defaults false; when true, max_records must be 1–100000. These policies expose bounded state operations; ordinary agent SQL permissions still come from grants in the schema assets. They do not require HTTP/MCP create routes.

The vector extension is enabled before schema/seed initialization. SQL assets are native SQL, not psql backslash commands or shell scripts. Initialization completes before the application starts. Invalid constraints or vector dimensions fail startup. Document vectors must already be populated using the query embedding representation; seed loading makes no embedding calls.

Connect the application

For libpq/Psycopg, set host database.sandbox.test, port 15432, database support, user agent, and the same synthetic password. Use sslmode=verify-full and sslrootcert=/opt/interceptor/tls/ca.pem. Declare a password variable with the same value in credentials, accepted by database. Node pg needs its normal ssl.ca configuration. Python Certifi settings do not configure libpq trust.

Authentication uses SCRAM-SHA-256. Required channel binding is unsupported because the proxy terminates TLS. COPY and replication are unsupported. Ordinary prepared queries, parameters, transactions, savepoints, and cursors use native execution. Connection, result, and storage bounds still apply; the storage watchdog is not an exact filesystem quota and can briefly overshoot during writes.

The first wrapper build downloads checksum-pinned database sources and compiles them inside Docker. Subsequent builds can reuse layers. Install only the target's driver dependencies in its application image; do not embed a running database or mount database files as application mutable roots.

Verify state and evidence

Exercise startup, a populated query, a representative committed transaction when applicable, and retrieval with the real query embedding. Native evidence records queries, parameters, results, SQLSTATE errors, and transaction state, excluding authentication exchanges. A successful statement inside an open transaction does not establish commit.

database_query_match oracles use sealed read-only SQL and expected row arrays. They compare independently observed database state with a baseline; positive observations do not automatically establish causation. Managed snapshots coordinate database logical state with other declared state and start a fresh database on restore. In-flight connections/transactions and external databases are not captured. For exact restore and oracle semantics, use the release's PostgreSQL reference.

Closed DNS and HTTP/TLS routing

These facilities belong under network, not services:

Object/field Configuration
dns.enabled Enable synthetic name resolution.
dns.listen Loopback port 53, normally 127.0.0.1:53.
dns.unknown_policy nxdomain by default, or refused.
dns.max_queries Default 10000, range 1–1000000.
http.enabled, http.listen Optional exact-host HTTP front door, normally 127.0.0.1:80.
tls.enabled, tls.listen Optional HTTPS front door, normally 127.0.0.1:443; DNS required.
tls.trust_mode auto, bundle, or application-managed.
tls.python_environments Optional absolute image interpreter paths under auto trust.
tls.application_managed_probe Required executable argv for application-managed trust.

Declared names resolve to loopback; DNS never forwards to upstream resolvers. Unknown names produce coverage gaps. The front doors route exact hostnames; TLS requires matching SNI and HTTP Host and uses a build-generated sandbox CA.

auto configures supported PEM trust stores and variables. For Certifi-based clients, declare the image's Python interpreter paths; Interceptor adds the CA during wrapper build without downloading dependencies. bundle provides /opt/interceptor/tls/ca.pem and INTERCEPTOR_CA_BUNDLE for explicit client configuration. application-managed additionally requires a probe that validates the supplied INTERCEPTOR_TLS_PROBE_URL. Do not disable certificate verification.

Synthetic identity and credential delivery

Identity belongs under identity. It models local callers and grants, not production credentials or an external identity provider.

Collection Fields and behavior
issuers Required id, kind: oidc, listen, hostnames, issuer_url; optional access_token_ttl_seconds defaults 900, range 1–86400. URL is an HTTP origin matching its loopback listener/declared hostname.
principals Required id, kind (agent, user, service), issuer; optional claims. Agent/service principals may have client_id and synthetic client_secret; users may not. Reserved JWT/actor claims cannot be overridden.
grants id, principal, service, scopes authorize direct access to a protected service.
delegations id, agent, user, service, scopes authorize one agent acting for one same-issuer user.
deliveries Common id, kind, issuer, principal, plus the kind-specific fields below.
inbound Optional issuer, agent-principal audience, and application_header: Authorization for HTTP caller identity delivery.

Supported delivery kinds:

Kind Additional fields
oauth_client client_id_environment, client_secret_environment, token_url_environment.
projected_jwt audience, path below /run/interceptor-session/identity/, environment_variable.
aws_container_credentials endpoint_environment, authorization_token_environment; generated endpoint is loopback.

Delivery-generated variable names must be unique and must not conflict with launch variables or static credentials. OIDC supports client credentials, discovery/JWKS, and same-issuer token exchange, not arbitrary production identity flows. Verify the agent's actual token acquisition and protected-service operation. Identity and grants participate in the managed environment's recorded state; live external identity does not.

Minimal issuer fragment:

identity:
  issuers:
    - id: sandbox-identity
      kind: oidc
      listen: 127.0.0.1:18300
      hostnames: [identity.sandbox.test]
      issuer_url: http://identity.sandbox.test:18300
      access_token_ttl_seconds: 900

Static synthetic credentials live under top-level credentials, each with id, environment_variable, value, and accepted_by. The accepting service must be declared, or use model-proxy for SDK credentials accepted by the model connector. The identity reference details issuer endpoints and complete flows.

Filesystem and capture services

filesystem.seed entries require blueprint-relative source, absolute container target, and boolean read_only. Writable seeds must be inside declared mutable roots. Optional injection_namespaces contain id, root, optional allow_create, and creation bounds max_files/max_file_bytes; they expose logical bounded file surfaces, not arbitrary host paths. Ordinary native logging needs mutable roots, not a file-injection namespace.

Capture endpoints use top-level attacker_services and kind: http_sink:

attacker_services:
  - id: capture
    kind: http_sink
    listen: 127.0.0.1:18400
    hostnames: [capture.sandbox.test]
    response:
      mode: static
      status: 200
      json: {received: true}
    max_capture_bytes: 1048576
    options:
      methods: [POST]
      paths: [/collect]

id, loopback listener, hostnames, and response status define the endpoint. Choose at most one response json or body; optional mode defaults static. dynamic requires a body-capable 2xx status and enables bounded response changes. Methods and paths are optional allowlists; requests outside them fail closed. Capture defaults to 1 MiB and retains bounded request data as native evidence. This is a local endpoint, not an external network destination. Destination, status, and allowlists stay sealed. Verify capture with synthetic data and inspect its evidence.

Model connectors and declared external HTTPS

The target's generation and embedding SDKs point to the local model proxy. Real provider configuration and authentication live on the host; see setup. Model inference and remote embedding computation are not simulated databases or restorable remote state. Query/document embedding compatibility remains the application's responsibility.

An explicit network.https_seams entry contains id and hostname. DNS and TLS must be enabled; application URLs and synthetic credentials use that declared name. The host separately binds it to an approved HTTPS origin and authentication using interceptor run --https-seam-config FILE.

network:
  dns: {enabled: true}
  tls: {enabled: true, trust_mode: auto}
  https_seams:
    - {id: tracing, hostname: tracing.sandbox.test}

This is real external forwarding through a host connector, not simulation or general egress. Remote effects are not rolled back by a snapshot. The bounded exchange does not provide streaming, gRPC, WebSockets, CONNECT, or automatic redirect following. Use the release's HTTPS seam configuration for the separate host binding file and its authentication. Preserve TLS verification and verify the actual application's request path.

Validate the modeled world

interceptor environment validate ./interceptor-environment --json
interceptor environment seal ./interceptor-environment
interceptor app build --environment ./interceptor-environment --tag agent-sandbox:local
interceptor app verify --environment ./interceptor-environment

Then start the target and exercise each modeled dependency. Inspect failures and coverage gaps; validation checks structure and references, not behavioral fidelity. Document any unsupported dependency. If state restoration is part of the claimed workflow, verify reads after restoration, including the agent's own saved context.