site.yaml configuration reference
Every key of a site's site.yaml, what it does and its default.
One folder holds everything specific to a site: site.yaml, the tag, alarm and interlock lists beside it (tags.csv, alarms.csv, interlocks.csv), the documents manifest and the code exports. Paths in site.yaml are relative to that folder. Keep the folder in version control.
The site folder is deploy/config/site/ on the edge PC, which every service reads as /config/site; BOOLE_SITE_DIR names another path inside the containers. When the folder holds a site.yaml, its plant is the default plant. BOOLE_PLANT and the tools' --plant option select another plant by ID or by folder path. The deployment profile is not in site.yaml: it is deploy/config/profile (Deployment profiles).
id: dairy
title: Dairy site, CIP skid 1
site: dairy-site
project: cip
customer_site: true
exports: {siemens: plc/siemens}
default_vendor: siemens
manifest: docs/manifest.yaml
alarm_list: DAIRY-ALARMS@A
cause_and_effect: DAIRY-CE@A
endpoints: {opcua_url: "opc.tcp://plc1.control.local:4840"}
glossary: {return pump: P-104}
prompts:
default: [Why did the CIP stop?, Which alarms came first?]
kpi:
baseline_median_minutes: 45
timezone: Europe/Dublin
shifts: {early: "06:00-14:00", late: "14:00-22:00", night: "22:00-06:00"}Identity and code
id
The plant's ID, unique on the edge PC; selects it with BOOLE_PLANT and --plant. Required.
title
The plant's name as people know it. Required.
site
The site name that starts every source ID (plc://<site>/…). Required. Never change it after go-live, or earlier citations stop resolving.
project
The code project name. Code projects are <project>-<vendor>, for example cip-siemens. Required.
exports
The code export per vendor key, a file or a folder: {siemens: plc/siemens, rockwell: plc/line.L5X}. Vendor keys are in Code importers. Required.
default_vendor
Which of exports is imported and used by default. Required.
sources
The folder of the IEC 61131-3 structured text sources the bench soft PLC runs. Optional; a site leaves it out.
hmi
The HMI tag and alarm exports (WinCC or FactoryTalk View) linked to the PLC tags. Optional.
customer_site
true on every customer site: the development profile is then refused at start-up. Default false.
Documents and lists
manifest
The documents manifest: documents, drawings, work-order and parts exports with their mappings (Documents and work orders). Required.
fds
The functional design specification: {file: docs/FDS.md, doc_id: FDS-CIP-01@A}. Optional; list the FDS in the manifest as well so that it is searched and cited.
alarm_list
The document ID and revision cited for each alarm row of alarms.csv, for example CIP-100-ALARMS@A. Required.
cause_and_effect
The document ID and revision cited for each interlock row of interlocks.csv, for example CIP-100-CE@A. Required.
safety_procedure
The site procedure section cited whenever an answer involves a safety function, as DOC@REV#section, for example SP-CIP-01@A#3. BooleX never advises resetting or bypassing a safety function. Optional, recommended.
isolation_procedures
The isolation or lock-out procedure per asset, cited by the maintenance briefing: {P-101: LOTO-P101@A#3}. BooleX never composes isolation steps itself. Optional.
document_sources
The document sources read in place, each {id, kind, label} with a path (a share mounted read-only on the edge PC) or a url (a server or cloud source): [{id: plant-share, kind: share, path: /mnt/docs, label: "Plant documents share"}]. Kinds: share and sharepoint_server in every profile; sharepoint, onedrive and google_drive only in the hybrid and client-cloud profiles, where both url and the identity endpoint must be in approved_endpoints (an approved address also approves the addresses under it). Default: none. See Documents and work orders and, for granting access, Connect a document share.
| Key | Kinds | Meaning |
|---|---|---|
url | all but share | sharepoint, onedrive: https://graph.microsoft.com/v1.0. google_drive: https://www.googleapis.com/drive/v3. sharepoint_server: the site, e.g. https://sp.plant.local/sites/engineering |
folders | all but share, required | Only these are read, with their subfolders. sharepoint: Library or Library/Folder (Documents, or Shared Documents). onedrive: folders in the drive, / for all of it. sharepoint_server: folders relative to the site. google_drive: folder IDs |
site | sharepoint | The Graph site, <host>:/sites/<name>, e.g. contoso.sharepoint.com:/sites/Plant |
drive | onedrive, google_drive | OneDrive: the drive ID (required). Drive: the shared drive's ID, for a folder in a shared drive |
tenant, client_id | sharepoint, onedrive | The Microsoft Entra tenant and the app registration's application (client) ID |
secret_file | all but share, required | The credentials as JSON, relative to the site folder unless absolute (mounted at /run/secrets/documents). sharepoint, onedrive: {"client_secret"}, or {"private_key", "certificate"} (PEM) for a certificate. sharepoint_server: {"username", "password"} or {"token"}. google_drive: the service account's JSON key as downloaded |
auth | sharepoint_server | basic (default) or bearer. NTLM and Kerberos are not supported |
ca_file | sharepoint_server | The site CA certificate (PEM) the server's certificate is issued by |
token_url | sharepoint, onedrive, google_drive | The identity endpoint, if not the default (https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token, https://oauth2.googleapis.com/token) |
page_cache
The cached images of cited pages, shown in the source viewer while a document's source cannot be reached: {enabled: true, path: /data/page-cache, cap_mb: 50, expiry_days: 30}. Off by default.
glossary
The names the floor uses, resolved to asset, tag and alarm IDs before searching: {return pump: P-104, heater: [HE-101]}. Optional.
prompts
Starter prompts per asset, else default; at most 5 are shown. Optional.
Live data
endpoints
The live sources for ingest (environment variables override them): opcua_url, modbus_host, modbus_map, mqtt_host, bacnet_host, bacnet_points, snmp_host, snmp_points, snmp_engine_id, dnp3_host, dnp3_points, iec61850_host, iec61850_points, iec61850_journal. See Data sources and connectors.
opcua
OPC UA security: policy, mode, client_cert, client_key, trust_dir, crl_dir, username and password_file (or user_cert and user_key). Read by ingest. See Data sources and connectors.
historian
The site historian to read instead of the platform store: {product: ignition, prefix: "[default]CIP/"}, with BOOLE_SITE_HISTORIAN_DSN; or AVEVA PI with product: pi_web_api, base_url (https), data_server, prefix, asset_database (event frames), alarm_pattern, ca_file, tag_list (tags.csv, its pi_point column) and username with BOOLE_SITE_HISTORIAN_PASSWORD_FILE, or BOOLE_SITE_HISTORIAN_TOKEN_FILE. See Connect a historian.
cmms
The live CMMS connector for the cmms service: product (sap_pm, maximo or sql), base_url, username, password_file or api_key_file, dsn_file and query for SQL, interval_s (900) and fields to override field names. See Data sources and connectors.
soe
Overrides of the sequence-of-events thresholds: response_s (10: a device's feedback within this time of its command is routine), routine_changes (20) and window_min (10: a tag changing more than this often in this window before the event is routine), settle_s (20: start-up transients). Other keys are refused. See Sequence of events.
Measurements and warnings
kpi
The pilot measurements: baseline_median_minutes (the week-0 median time to diagnosis from the site's timing study), timezone, and shifts ({name: "HH:MM-HH:MM"} in that time zone; a shift may run past midnight). The shifts also trigger the shift handover workflow.
early_warning
Drift and slow-start notices: key_tags ({TAG: ASSET}), hold_s (30) and starts ([{asset: P-101, steps: [10, 20]}]). See Early warnings.
residual_monitoring
Validated models replayed on live data: interval_min (15), max_validation_age_days (90), and assets, each with model, output, threshold, trend_h, hold_h, parameter, label and bounds. See Early warnings.
workflows
The workflow definitions file, for example workflows.yaml. Without it, no workflows run. See Workflow inbox.
Inputs, privacy and models
training
true turns on training mode: past stops with a confirmed diagnosis replayed for trainees with the cause hidden, then scored. Default false. See Training mode.
inputs
Voice and photo input: {voice: "http://whisper:9000", photo: true}. Off unless set. See Photo and voice input.
media_retention_days
Days journal photos are kept before deletion. Default 30.
approved_endpoints
The hybrid profile's approved model endpoints. Empty: none is accepted. See Deployment profiles.
machine_types
The machine types at the site, for knowledge packs: per type, builder, assets, and for a builder exporting, projects and fault_library. See Build a knowledge pack.
machine_builders
Per builder: public_key (the key the site trusts for its packs) and share_fixes (default false).
How answers are made (llm.json)
These keys are not in site.yaml: they sit beside the model endpoint in deploy/config/llm.json (Architecture).
| Key | Default | What it sets |
|---|---|---|
agents | false | Focused agents: a Lead investigator and specialists by expertise. Experimental |
challenge_rounds | 2 | Rounds in which the specialists dispute each other's claims, on top of the 6 investigation tasks (0 to 5) |
agents_time_budget_s | 20 | Seconds of specialist work per question; at the limit the Lead answers with what it has (more than 0, at most 120) |
two_pass | false | The two-pass answer: candidate devices first, then each one argued |
candidates_shown | 3 | Causes shown in full; the rest are listed as other possibilities (1 to 10) |
early_candidates | false | One short call lists candidate causes from the evidence before the answer, shown at once as First candidates with their sources; the checked answer replaces them. One extra model call per question |
quick | none | A second model endpoint (provider, base_url, model, as for chat) for that candidate-listing call, checked against the deployment profile like chat. Without it, the chat model makes the call. It also makes the first look at each prepared stop, which is shown within seconds as "First look — being checked" until the chat model's checked diagnosis replaces it. Without it, only the checked diagnosis is prepared |
Bench and evaluation keys
These are used only by the bench simulator and the evaluation harness. A customer site leaves them out.
library
The fault library: the ground truth of the recorded faults, for evaluation.
alarm_count
The expected range of alarm definitions, [min, max], checked by the evaluation.
simulator
The plant model for the bench simulator: model, faults, start, unit_start and bad_when_false.