# 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

```sh
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](bring-your-agent.md) to choose the correct interface.

A typical directory is:

```text
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](services.md). |
| `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.

```yaml
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](https://docs.intrusive.ai/pages/guides/customer-support-environment.html#add-the-invocation-adapter-and-native-logging).

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](sessions-and-evidence.md#collect-native-application-logs)
and confirm the resulting file exists before claiming retention.

## Validate, seal, build, and exercise

After completing review metadata and real image identity:

```sh
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](sessions-and-evidence.md).

Use the [support-agent recipe](https://docs.intrusive.ai/pages/guides/customer-support-environment.html)
for a coherent example. The selected release's
[field reference](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/environment-blueprint.md)
provides exact less-common options; switch its repository tag to your release.
