Configuration#
How Settings Are Applied#
Edit .env.example in the repository root. Every make up copies it to .env,
so changes made directly to .env are overwritten.
What you changed |
Apply with |
|---|---|
|
|
|
|
make restart restarts the agent with its current settings. It does not apply
.env.example changes, including service URLs; use make up for those.
Settings You Must Change#
Where |
Setting |
Why |
|---|---|---|
Agent |
Service URLs, for example |
Empty means the agent has no data from that service |
Agent |
|
Lists the service hosts so the agent reaches them directly |
Agent |
|
Must point at a downloaded model, or |
Each service host |
Agent event URL and store ID |
Without them the service sends no events, or they are rejected |
Every host |
NTP time synchronization |
A clock two minutes off makes every decision for that host’s events fail |
See Connect Store Services and Send Events From Store Systems.
Main Settings#
Variable |
Default |
Description |
|---|---|---|
|
|
Host directory that holds downloaded models |
|
|
Model served by the OpenVINO™ Model Server. Use an OpenVINO™ model with tool-calling support, for example |
|
|
Interface the operator UI listens on. Use |
|
|
Operator UI port |
|
|
Host port for the model server API (loopback only) |
|
|
Host port for the weather service (loopback only) |
|
|
Seconds to wait for one agent answer |
|
empty |
Comma-separated LAN hosts the agent must reach without the proxy |
Image Source#
Variable |
Default |
Description |
|---|---|---|
|
|
|
|
|
Registry and namespace prefix |
|
|
Image tag |
make up # pull intel/qsr-agent:latest
make up REGISTRY_URL=myreg.io/team/ TAG=2026.2.0 # custom registry and tag
To build locally, see Build from Source.
Weather#
By default the weather service is a simulator that you control with
make weather. To report live conditions for the store location instead, add
these lines to .env.example:
WEATHER_BACKEND=open-meteo
WEATHER_LATITUDE=12.97
WEATHER_LONGITUDE=77.59
WEATHER_LOCATION_NAME=My Restaurant
WEATHER_STORE_ID=qsr-001
Important
Open-Meteo’s free API is for non-commercial use. Commercial deployments need a paid key or a self-hosted instance.
Connect Store Services#
Store systems connect to the agent as MCP services. They are listed in
agent-config/hermes/remote-mcp.example.yaml. Each entry needs a URL that the
agent container can reach:
mcp_servers:
your-service:
url: https://your-service.example.internal/mcp
transport: streamable-http
enabled: true
connect_timeout: 15
timeout: 120
headers:
Authorization: Bearer ${YOUR_SERVICE_MCP_TOKEN}
Same machine: use
host.docker.internalinstead of127.0.0.1. Inside the container,127.0.0.1refers to the container itself.Another machine: use its IP address or DNS name. If a proxy is set, add the host to
QSR_EXTRA_NO_PROXY.Disable a service: set
enabled: false.
The preconfigured entries read their URLs from .env.example. Leave a URL
empty to skip that service. After changing a URL, run make up:
Service |
Purpose |
Setting |
|---|---|---|
|
Store-location weather |
|
|
Kitchen food-safety events |
|
|
Self-checkout loss events |
|
|
Take-away order accuracy |
|
|
Dine-in order accuracy |
|
|
Queue, menu, and kiosk settings |
|
|
In-store advertising |
|
|
Café-day orders, customers, and queue |
|
|
Table occupancy and cleaning |
|
|
Zone footfall and busy hours |
|
Services that are not running appear as unavailable in Connected apps. The agent keeps working with the services it can reach.
After editing agent-config/hermes/remote-mcp.example.yaml, run
make restart. Self-signed HTTPS certificates on service endpoints are trusted
automatically each time the agent starts. If a service regenerates its
certificate, run make restart.
Send Events From Store Systems#
Store systems send events to the agent with an HTTP POST to
http://<agent-host>:8600/autonomy/events. See the
API Reference for the event format.
On each service host:
Set the service’s event URL to the agent’s
/autonomy/eventsendpoint.Set the store ID to the agent’s
QSR_RESTAURANT_ID(defaultqsr-001), or the agent rejects the events.Behind a proxy, let the service reach the agent host directly.
Send only events that may need a decision. Each event costs a model run and an operator review.
To check the connection, run curl -s http://localhost:8600/status?force=1:
every connected service is listed with "ok": true. Ask a question about the
service in Operator Chat, then send an event from the service and confirm
it appears in Autonomy Decisions.
Operating Notes#
Restarts: after restarting a service, run
make restartso the agent reconnects.Clocks: keep the agent and service hosts synchronized (NTP). The agent refuses to act on a service snapshot more than 120 seconds old, so a host whose clock is behind makes every decision for its events fail with a clock-skew error.
Security:
/autonomy/eventshas no authentication. Keep it on the store network or behind an authenticating proxy.
Proxy#
Export proxy variables in the shell before make up. They are passed to image
builds and containers:
export http_proxy=http://proxy.example.com:8080
export https_proxy=$http_proxy
export no_proxy=localhost,127.0.0.1,::1
If your proxy intercepts TLS, configure the system or Docker daemon to trust the organization’s CA. Do not disable TLS verification.
Secure Network Access#
The operator UI has no built-in login. Anyone who can reach port 8600 can chat with the agent and approve actions. For any deployment beyond a lab:
Set
QSR_UI_HOST=127.0.0.1and reach the UI through an SSH tunnel or an authenticating reverse proxy:ssh -L 8600:127.0.0.1:8600 user@agent-host
Restrict port 8600 to the store network and the systems that send events.
Use HTTPS and authentication (a bearer token or mTLS) on every remote store service.