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.