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. In the reviewed validator 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. The customer-support agent does not create its own log file; its CLI logs to stderr and library callers choose handlers.

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.