Enable DiAGRI¶
This page is for an operator who already runs the bridge-only daemon and wants to switch DiAGRI on: the configuration fields, the write host, the first operator, where credentials come from, how to start serve and how to check it. It also shows how to switch the mode off again.
What enabling gives you today. With
auto_research = true,servestarts the runtime, runs the executor about once a second, mounts the workbench routes under/wband, whenrolesis set, runs open model tasks every 30 seconds. An operator starts a round through those routes: project, research protocol, round, model call budget and goal; see Run a research round. The operator console at/workbenchis the page for it; there is no CLI command. What a real model does with a goal has not been run: the tests use a scripted model.servesends an external heartbeat only when both heartbeat URLs are set in the environment (see Notifications, daily reports and backup), and it starts the compute service only when all of its nine settings are present (step 5). All of it has been tested on the simulated AC5 only. See Status and known limitations.
Before you start¶
- The bridge-only install works:
.venv/bin/growbridge statusprints the device state. If it does not, go to Installation and quick start. - You know which configuration file the daemon uses. The default is
~/.config/spiderfarmer-growbridge/config.toml. For another file, put--config /absolute/path/to/config.tomlbefore the subcommand in every command below. - To see the mode work without a device, run
.venv/bin/growbridge simulatefirst. It needs no configuration and prints a summary with"stage": "ended". See Tutorial: a simulated research round.
1. Stop the daemon¶
Stop serve with Ctrl-C. If it runs as a background service, remove the service for now:
.venv/bin/python scripts/install_macos.py --uninstall # macOS
.venv/bin/python scripts/install_linux.py --uninstall # Linux
The configuration file is read once, when serve starts.
2. Set the configuration fields¶
Add the top-level fields before any [roles.*] table, because TOML assigns every key after a table header to that table.
auto_research = true
controls_enabled = true
lan_bind = "YOUR_LAN_ADDRESS"
lan_port = 9443
lan_hosts = ["YOUR_LAN_HOST"]
overlay_hosts = ["YOUR_OVERLAY_HOST"]
report_time = "08:00"
report_timezone = "Europe/Helsinki"
backup_dir = "/absolute/path/to/backup"
backup_interval_seconds = 21600
[roles.planner]
model = "claude-opus-5-5"
effort = "medium"
max_tokens = 16000
| Field | Set it to | If you leave it out |
|---|---|---|
auto_research |
true |
The daemon runs in bridge-only mode. |
controls_enabled |
true |
Every write is refused with controls_disabled, so the executor cannot act. |
lan_bind, lan_port |
The address and port of the on-site listener. Give it a port of its own, not port. |
Both are needed to start the listener. Without them there is no LAN entry and irrigation is refused with entry. |
lan_hosts |
The host names or addresses an on-site client puts in its Host header. |
No request can be a LAN entry request. |
overlay_hosts |
The host name of the overlay address. | There is no overlay entry. |
report_time, report_timezone |
HH:MM and an IANA zone name. |
08:00 and UTC. |
backup_dir, backup_interval_seconds |
A directory on independent media, and seconds between backups (60 or more). | No backups and a standing backup_unconfigured warning. The interval defaults to 21600. |
[roles.<name>] |
One table per model role: orchestrator, planner, researcher. |
With no table at all, model roles are off. With at least one, a role without a table uses the defaults. |
Things the loader in config.py and the entry check in workbench/auth.py do with these fields:
- An unknown field name makes
servefail at start, at top level and inside a role table. - A host listed in both
lan_hostsandoverlay_hostsis no entry at all. - The overlay entry is the loopback listener
127.0.0.1:<port>. A request counts as overlay when it arrives there with aHostheader listed inoverlay_hosts. The repository ships no proxy and no overlay network setup: you need your own HTTPS reverse proxy that forwards to that listener and keeps theHostheader. Not verified. - Of the role fields, the code reads
model,effort,max_tokensandtools.provider,max_callsanddataare checked when the file is loaded and are not read anywhere yet.
The full list of fields is in the Configuration reference. Report and backup behavior is in Notifications, daily reports and backup.
3. Register the write host¶
You should see Write host registered: <host id>. The id is kept in host_id in the data directory. Running the command twice is harmless.
If it is refused with another host is registered for this device, the control database already names another machine. See "Restore from backup or a new write host" in the Troubleshooting runbook.
Do this before starting serve. A daemon that starts unregistered keeps the BLE connection closed, raises the alert runtime / write_host and refuses writes until it is registered and restarted.
4. Add an operator¶
The command asks for the secret twice and never takes it as an argument. The secret needs 12 to 256 characters. You should see Operator added: YOUR_OPERATOR. Only a salted hash is stored.
| Message | What to do |
|---|---|
the secret needs at least 12 characters |
Choose a longer secret. |
the two entries differ |
Run the command again. |
operator 'YOUR_OPERATOR' already exists |
Use another name. There is no command to remove an operator or change a secret. |
5. Put credentials in the environment¶
No credential goes into the configuration file. serve reads them from its own environment.
| Purpose | Where it comes from |
|---|---|
| Model calls | The Anthropic SDK reads its own variables; the tests set ANTHROPIC_API_KEY (tests/agents/test_agents_llm.py). The SDK is the optional extra agents in pyproject.toml: .venv/bin/python -m pip install '.[agents]'. Its version is not pinned in constraints-tested.txt. |
A model role calling /wb over HTTP |
GROWBRIDGE_ROLE_TOKEN_<ROLE>, for example GROWBRIDGE_ROLE_TOKEN_PLANNER, sent as Authorization: Bearer .... At least 32 characters; a shorter one stops serve at start. The model tasks that serve runs itself do not use these tokens. |
| Notifications | GROWBRIDGE_TELEGRAM_*, GROWBRIDGE_EMAIL_TO, GROWBRIDGE_SMTP_*. See Notifications, daily reports and backup. |
| Compute service on CSC | FIRECREST_URL, FIRECREST_TOKEN_URL, FIRECREST_CLIENT_ID, FIRECREST_CLIENT_SECRET (a CSC robot account), FIRECREST_SYSTEM (cpu or gpu), FIRECREST_ACCOUNT (the CSC project) and FIRECREST_WORKDIR, plus the settings compute_templates_dir and compute_member. All nine or none. See below. |
| External heartbeat | GROWBRIDGE_HEARTBEAT_HOST_URL and GROWBRIDGE_HEARTBEAT_RUN_URL: both or neither. One alone stops serve; neither leaves the standing warning monitor_unconfigured. See the same page. |
Compute service (optional). serve starts it only when all nine settings are present. With some missing it starts without it and the log names what is missing (never a value); a bad template or an invalid project setting stops serve.
- Install the optional client:
.venv/bin/python -m pip install pyfirecrest. It is not inconstraints-tested.txt, and nothing here has run against the real CSC service. - Put one reviewed template per JSON file into
compute_templates_dir(the fields ofJobTemplateincompute/backend.py). Thescriptis a Slurm batch script: it must start with#!, must set a time limit (#SBATCH --time) and must not set its own job name. A free text parameter must declare apattern; the rules are in Configuration reference. Parameters reach it only as the environment variablesDIAGRI_PARAM_<NAME>, input locations asDIAGRI_INPUT_<NAME>, and results must be written toDIAGRI_OUTPUT_DIR. The service logs each template's id, version and file digest at start. - FirecREST reports no project balance. Read it in MyCSC and enter it:
POST /wb/compute/balancewith{"cpu_hours": 500}. Then give each research task a budget:POST /wb/compute/tasks/TASK_ID/budgetwith{"cpu_hours": 40, "storage_gb": 20}. Until both exist every submission is refused withquota. Both need a recent re-authentication. - The API reports no CPU use either, so each job is charged at its template's full
max_cpu_hours. Enter a fresh balance from MyCSC from time to time;GET /wb/computeshows the entry, the budgets, what is used and reserved, and the open jobs.
The installers in scripts/ write no environment into the launchd or systemd service. To use these variables in a background service you have to add them to the service definition yourself. Not verified. A real model call has not been made in any test either: the tests stub it.
6. Start the daemon¶
serve listens on 127.0.0.1:<port> and, when lan_bind and lan_port are set, on that address as well. Lines to look for in the log:
| Log line | Meaning |
|---|---|
not the registered write host: the BLE connection stays closed |
Step 3 was skipped. Stop, register, start again. |
the device did not identify itself within 20.0 s |
The AC5 did not answer. The daemon keeps running and keeps trying. |
model roles are off: ... |
roles is set but the SDK or its credentials are missing. Everything else still runs. |
growbridge: the token of role '...' is shorter than 32 characters |
serve stopped. Fix the role token. |
The two real listeners are not covered by a test; the tests reach the same application in process.
7. Check that it is up¶
.venv/bin/growbridge statusstill prints the device state.- The workbench is mounted. A request without a session is answered
401with codesession;404means the daemon is in bridge-only mode.
- Log in on the LAN entry. You can do this in the console (item 4 below) or send the request yourself with any HTTP client that keeps cookies. Run a research round lists the headers every request needs.
POST /wb/login
Host: YOUR_LAN_HOST:9443
Origin: http://YOUR_LAN_HOST:9443
x-growbridge-ui: 1
Content-Type: application/json
{"name": "YOUR_OPERATOR", "secret": "YOUR_OPERATOR_SECRET"}
You should get {"operator": "YOUR_OPERATOR", "entry": "lan", "reauth_seconds": 300} and the cookie growbridge_operator, valid for 8 hours on paths under /wb.
4. To use the operator console instead, open the entry address followed by /workbench, for example http://YOUR_LAN_HOST:9443/workbench, and sign in with the account you made with growbridge operator add in step 4. The console is served only in DiAGRI mode; in bridge-only mode /workbench answers 404. It shows times in the zone set by report_timezone (UTC by default). The device-write buttons need the same registered write host as the routes.
5. GET /wb/alerts with that cookie returns {"alerts": [...]}. On a new setup expect backup_unconfigured when backup_dir is unset, and model_client when model roles could not start. runtime with key write_host means the host is not registered. With no notification channel configured, expect the standing warning notify_unconfigured: alerts are recorded but not sent; see Notifications, daily reports and backup.
6. The bridge write endpoints POST /control/{device}, POST /outlet and POST /pump now answer 403 with Device writes go through the workbench. The dashboard controls and the MCP write tools call those endpoints, so they stop working; reading still works.
8. Approve the safety configuration¶
Protection rules exist only after an operator approves a safety configuration. Within 300 seconds of logging in or re-authenticating, send:
POST /wb/safety/approve
{"config": {"version": 1, "rules": [{"id": "overheat-light-off", "sensor": "temp", "unit": "C",
"validity_seconds": 20, "trigger": {"op": ">", "value": 35}, "duration_seconds": 30,
"action": {"channel": "light", "level": 0}}]}}
You should get {"protection_right": <number>}. A configuration with a NaN or an infinite number is rejected with 422, and the configuration approved before stays in force. The rule above is the one in the simulator fixture (sim/fixtures.py); it is an example of the shape, not a recommended setting. What protection rules may do is explained in the Control and safety model.
When a step is refused¶
| You see | What to do |
|---|---|
400 Invalid host header |
The Host you used is not in lan_hosts or overlay_hosts. Add it and restart. |
403, code entry, on login |
The host and the listener do not match: a LAN host must arrive on lan_port, an overlay host on port. 127.0.0.1 is not an entry. The same code is returned when the Origin or x-growbridge-ui header is missing. |
401, code session |
Wrong name or secret, or the session expired. Log in again. |
429, code locked |
Five failed attempts for this name from this address inside 15 minutes. Wait. |
403, code reauth_required |
Send POST /wb/reauth with {"secret": "..."} and repeat the request. |
A daemon already owns this data directory |
Another serve is running on the same data_dir. |
All codes are listed in Denial codes and stage events.
Switch it off again¶
- Stop every live stage first:
POST /wb/stages/STAGE_ID/stop. Once the mode is off nothing follows a run sheet, and care rules and protection rules no longer run. - Stop the daemon, set
auto_research = falseand startserveagain. The other fields may stay; bridge-only mode ignores them. - Check: the
curlcommand in step 7 now prints404, and the bridge write endpoints accept writes again whencontrols_enabledistrue.
The databases, the operators and the write-host registration stay in the data directory. When you switch the mode on again, the start is handled like any restart: every stage that is not ended or stopped goes to recovery_check. See Troubleshooting runbook.
See also¶
- Run a research round
- Configuration reference
- CLI reference
- Control and safety model
- Status and known limitations
Pages were last checked against the code on 2026-11-11. DiAGRI mode has been tested on a simulated AC5 only: see Status and known limitations. To change a page, read how this wiki is edited first.