# 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](environment-blueprints.md).
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:

```yaml
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:

```yaml
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.

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

`assets/directory.yaml`:

```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:

```yaml
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:

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

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

```yaml
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.

```yaml
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:

```yaml
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](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/mcp-services.md)
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.

```yaml
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:

```sql
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`:

```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](https://docs.intrusive.ai/pages/guides/customer-support-environment.html)
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](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/postgresql.md).

## 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:

```yaml
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](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/identity.md)
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`:

```yaml
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](setup.md).
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`.

```yaml
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](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/https-egress.md)
for the separate host binding file and its authentication. Preserve TLS verification
and verify the actual application's request path.

## Validate the modeled world

```sh
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.
