Create an environment blueprint
A blueprint is a directory containing environment.yaml and all referenced assets.
It describes the agent and the synthetic world in which it runs. Keep campaign
objectives and scenario content in Operator's bundle, not in the environment.
Start with the application
interceptor environment init ./interceptor-environment
The starter refuses to overwrite an existing blueprint. Its HTTP example is a starting point, not a requirement to turn your application into an HTTP service. Use agent onboarding to choose the correct interface.
A typical directory is:
interceptor-environment/
environment.yaml
assets/
adapter/support_adapter.py
schema.sql
seed.sql
service-fixtures.yaml
Only include assets you actually reference. Paths stay inside the blueprint root; unknown fields, unsafe paths, missing assets, ambiguous fixtures, and invalid cross-references fail validation. Adapter directories have stricter link restrictions.
Choose a schema and fill the sections
Use api_version: interceptor.dev/v1alpha1 and kind: Environment for the base
format. Select interceptor.dev/v1alpha2 when using operation delivery metadata,
service export_contracts, or MCP implementation. These schema identities are
different from product versions and Operator's integration contract.
| Section | What to configure |
|---|---|
metadata |
Required name/version; description and actual reviewer identity/time. |
application.image |
Exact inspected image digest. |
application.launch |
Executable argv, absolute workdir, literal environment settings. |
application.interface |
Interface kind, named operations, readiness/startup and turn timeouts. |
application.persistence |
Snapshot capability, mutable roots, and quiescence behavior. |
network |
Closed DNS, HTTP/TLS front doors, trust, and optional declared HTTPS seams. |
filesystem |
Read-only or writable seed assets and optional bounded file namespaces. |
services |
Dependencies from the complete service reference. |
identity, credentials |
Synthetic identities, grants, deliveries, and local credentials. |
organization, time |
Optional organization context and simulated clock configuration. |
canaries, attacker_services, oracles |
Synthetic markers, capture endpoints, and deterministic checks needed by the environment. |
limits, adaptive |
Resource bounds, permitted feedback profiles, and attempt/artifact allowances. |
metadata.name is a lowercase DNS-like name starting with a letter, at most 63
characters. version is your environment version. reviewed_by and RFC 3339
reviewed_at must describe a real review; do not treat generated placeholders as
evidence of review. These fields are checked during
validation as well as sealing.
Launch variables are strings with no host interpolation. MODEL_BASE_URL names
the local model proxy, normally http://127.0.0.1:18080/v1 for OpenAI-compatible
SDKs. Other base URLs must use declared names or permitted local endpoints.
Declare credential-like variables in credentials with synthetic values and an
accepted_by service ID or model-proxy; keep real keys outside the blueprint.
Describe observable behavior
Choose named operations from the real invocation boundary. For a Python object,
code.initialize receives one dictionary and returns the object whose method is
named by code.invoke; input_mode: single passes decoded JSON as one value.
Use concurrency one for Python and for stateful adapters.
With v1alpha2, delivery or delivery_asset can describe the operation's input
contract for capability consumers. Describe actual inputs and leave unknown outputs
unknown. Exported examples must be synthetic public examples, not private seed records.
Allow feedback profiles deliberately: black-box, diagnostic, or oracle-assisted.
The running session selects one profile and cannot broaden it later. An oracle is
a deterministic check against recorded effects, not a model-generated opinion.
Available checks include output/model-output text, model tool calls, service/file
state, capture-sink observations, and managed database query outcomes. Keep checks
consistent with the evidence actually exposed to the campaign.
Retain the agent's native logs
Use persistent mutable filesystem roots for native log files. This means
declaring narrow writable directories in application.persistence.mutable_roots,
not making the container's / writable.
application:
persistence:
snapshot_capable: false
mutable_roots: [/state/support]
quiesce: {kind: none}
This is a fragment to merge into the complete application section. Configure the
agent's existing logging facility to write inside that root, for example
/state/support/logs/agent.log. A Python adapter can create the logs child and
install a standard logging.FileHandler, as shown in the
customer-support adapter example.
Interceptor provisions the mount, while the application can create and own its
children. Image-side ownership does not determine ownership of a replacement
mount. Avoid mounting over dependencies or existing required files. If initial
writable contents are needed, declare a filesystem.seed entry with
read_only: false and a target inside the mutable root.
Mutable roots retain session data even with snapshots disabled. They do not capture
process memory. If snapshots are enabled, flush the application's required state
and implement a defensible quiescence/save/restore mechanism. Disposable /tmp is
not a location for required retained logs.
Native log files, Interceptor journals, and Operator evidence are separate records. Writing a file does not automatically make its contents campaign observations or an evidence export. Use the documented collection procedure and confirm the resulting file exists before claiming retention.
Validate, seal, build, and exercise
After completing review metadata and real image identity:
interceptor environment validate ./interceptor-environment --json
interceptor environment seal ./interceptor-environment
interceptor environment inspect ./interceptor-environment --json
interceptor app build --environment ./interceptor-environment --tag support-sandbox:local
interceptor app verify --environment ./interceptor-environment
Sealing writes fingerprints into environment.lock.json. Changing assets, adapter
code, or behavior requires review, resealing, and wrapper rebuilding. app verify
checks build bindings; it does not prove the target can answer a support question.
Start and invoke the target as described in sessions.
Use the support-agent recipe for a coherent example. The selected release's field reference provides exact less-common options; switch its repository tag to your release.