Skip to content
Back to search

apollo-11

Eye of the System: an autonomous monitoring system for a simulated marketplace. Agents keep a typed metric graph, detect anomalies, investigate root causes, and report incidents with evidence. A2A specialists, an MCP server, and a web UI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hacklab11--apollo-11/badge.svg)](/listings/hacklab11--apollo-11)

HTML

<a href="/listings/hacklab11--apollo-11"><img src="/api/listings/hacklab11--apollo-11/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Docker with Compose v2 (including `!reset`/`!override` support). For the host demo CLI and development, install [uv](https://docs.astral.sh/uv/); the workspace uses Python 3.13.

cp .env.example .env
docker compose up -d --build --wait
uv sync --locked
uv run demo trigger s8

The installed CLI command is `demo trigger s8`; `uv run` selects the workspace environment. Open the **UI at http://localhost:8080** and **Grafana at http://localhost:3000**. The simulator is at http://localhost:8100; the MCP port defaults to the first free port in 8110–8119. `uv run demo status` shows simulator/Core status; `uv run demo narrate` prints the incident story.

Startup and smoke checks need no model key. Live investigations do: configure the provider/model under `llm` in [config/compose.yaml](config/compose.yaml) and the corresponding key in `.env`. Compose starts Core monitoring paused (`sim.autostart: false`); resume it in the UI after configuring a model. The simulator itself advances continuously. A credential-free, scripted S8 run is below.

Scale Detective without assigning fixed host ports:

docker compose up -d --scale detective=3
docker compose down

Named volumes retain data on shutdown. The S8 test requires a fresh project with no prior incidents; use a separate project name rather than deleting a live project's volumes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines
  1. # Eye of the System
  2. ![Eye incident workspace showing the S8 investigation, measured recovery and human closure](docs/images/incident-workspace.png)
  3. The React incident workspace after an offline S8 run with a scripted model: seller price typo, coupon ruled out, measured recovery and human closure after approved SellerOS reverts.
  4. Eye of the System monitors a marketplace's metric graph, ranks unusual changes by business impact, investigates explanations with evidence, and publishes incidents for human review. Deterministic warehouse tools compute the numbers; agents decide what to investigate and how to explain it. The included continuous simulator supplies S8: a seller's price typo during a planned electronics coupon day.
  5. ## Architecture
  6. The [Compose stack](compose.yaml) runs:
  7. - `sim` → hourly Parquet lake → `eye-data` (DuckDB, metric registry, graph and deterministic tools).
  8. - `eye-core` (FastAPI, DBOS workflows and incident control) with `postgres` for durable workflow/control state.
  9. - `sentinel`, `detective`, `skeptic`, `reporter`, `cartographer`: independently served A2A agents using PydanticAI and `agent_runtime`.
  10. - `eye-specialists`: Growth, Marketplace and Discovery A2A endpoints; `selleros`: independent seller-side service.
  11. - `web`: React workspace behind nginx; `eye-mcp`: MCP facade over Core.
  12. - `lgtm`: Grafana, logs, metrics and traces; `egress-proxy`: allowlisted agent internet access.
  13. - `auth`: OAuth client-credentials issuer and signing authority for A2A agent cards.
  14. See the [architecture](docs/specs/architecture.md) and [documentation index](docs/README.md).
  15. ## Quickstart
  16. Requires Docker with Compose v2 (including `!reset`/`!override` support).
  17. For the host demo CLI and development, install [uv](https://docs.astral.sh/uv/);
  18. the workspace uses Python 3.13.
  19. ```bash
  20. cp .env.example .env
  21. docker compose up -d --build --wait
  22. uv sync --locked
  23. uv run demo trigger s8
  24. ```
  25. The installed CLI command is `demo trigger s8`; `uv run` selects the workspace environment.
  26. Open the **UI at http://localhost:8080** and **Grafana at http://localhost:3000**.
  27. The simulator is at http://localhost:8100; the MCP port defaults to the first free port in 8110–8119.
  28. `uv run demo status` shows simulator/Core status; `uv run demo narrate` prints the incident story.
  29. Startup and smoke checks need no model key. Live investigations do: configure the provider/model under
  30. `llm` in [config/compose.yaml](config/compose.yaml) and the corresponding key in `.env`.
  31. Compose starts Core monitoring paused (`sim.autostart: false`); resume it in the UI after configuring a model.
  32. The simulator itself advances continuously. A credential-free, scripted S8 run is below.
  33. Scale Detective without assigning fixed host ports:
  34. ```bash
  35. docker compose up -d --scale detective=3
  36. docker compose down
  37. ```
  38. Named volumes retain data on shutdown. The S8 test requires a fresh project with no prior incidents;
  39. use a separate project name rather than deleting a live project's volumes.
  40. ## Service authentication
  41. Every A2A JSON-RPC call requires a short-lived RS256 JWT from `auth`. Scopes are
  42. `<agent>:<skill_id>`; Core's seller price-revert endpoints require `selleros:revert`
  43. instead of a static service token. The human operator token is unchanged. Missing or
  44. invalid JWTs return 401; insufficient scopes return 403 (or a failed multi-skill task).
  45. Agent cards and health endpoints remain public. Services enroll signed cards at startup;
  46. callers verify signatures against the issuer's JWKS before routing and reject unsigned
  47. or tampered cards. Being on a Compose network does not grant access.
  48. Copy the development-only `EYE_AUTH_<CLIENT>_SECRET` values from `.env.example` and
  49. replace them outside local development. Compose supplies each client only its own secret
  50. and uses `EYE_AUTH_URL=http://auth:8500`. Standalone callers set `EYE_AUTH_CLIENT_ID` and
  51. `EYE_AUTH_CLIENT_SECRET`; client scope grants and secret environment names live in
  52. `config/auth.yaml` (`EYE_AUTH_CONFIG` overrides the path). The issuer persists its key in
  53. the `auth-keys` volume (`EYE_AUTH_KEY_PATH` overrides the file path); retain it across restarts.
  54. Local Compose explicitly sets `AUTHLIB_INSECURE_TRANSPORT=1` for internal HTTP. Shared or
  55. production deployments must use TLS and remove that exception. See
  56. [Eye Auth](packages/auth/README.md) for endpoints and library usage. The offline gate below
  57. also checks missing-token 401, wrong-scope 403, and unsigned/tampered-card rejection.
  58. ## Connect real data
  59. Compose Core uses `EYE_DATA_URL=http://eye-data:8150`, not an in-process simulator.
  60. The data service's [ParquetLanding](packages/data/src/eye/warehouse/landing.py) imports published hourly
  61. partitions from `SIM_LAKE_DIR` (default `data/lake`). A real ingestion pipeline must supply the
  62. [warehouse schema](packages/data/src/eye/schema.py), including `partition_status` manifests, or implement
  63. the typed [warehouse operations](packages/data/src/eye/warehouse/operations.py) and point Core and agents'
  64. `EYE_DATA_URL` at that compatible service. Configure metrics, identities and causal seeds in `config/`.
  65. Changing the root data-source setting alone does **not** replace the Compose ingestion pipeline.
  66. For embedded/local Core without `EYE_DATA_URL`, implement
  67. [`DataSource`](packages/orchestrator/src/eye/datasource.py): `now`, `history_start`, `live_start`,
  68. `step()`, `cursor()` and `close()`. `data.source: duckdb` plus `data.path` selects the existing
  69. DuckDB adapter; `data.source: sim` selects the simulator. A new adapter also needs an `open_source()`
  70. dispatch branch. Settings are YAML, not a generic `EYE_DATA_SOURCE` environment override.
  71. See [data](docs/specs/data.md) and [deployment](docs/specs/deployment.md).
  72. ## Development
  73. ```bash
  74. uv sync --locked
  75. uv run ruff check . && uv run ruff format --check .
  76. uv run lint-imports
  77. uv run vulture
  78. uv run pytest -m "not live" -q
  79. uv run python scripts/agent_evals.py
  80. ```
  81. Normal tests and PR evals never call real models. See [AGENTS.md](AGENTS.md) for package boundaries,
  82. test policy and PR rules. Frontend commands are in [packages/web/README.md](packages/web/README.md).
  83. Run the offline integration gate in a fresh, isolated Compose project
  84. (choose a new project name for another run):
  85. ```bash
  86. export COMPOSE_FILE=compose.yaml:compose.e2e.yaml
  87. export COMPOSE_PROJECT_NAME=eye-s8-check
  88. export COMPOSE_DISABLE_ENV_FILE=1
  89. docker compose up -d --build --wait --scale detective=3 && ./scripts/smoke.sh && ./scripts/e2e-s8.sh
  90. docker compose down
  91. ```
  92. The override uses a scripted model provider and isolated test settings; do not use it for live investigations.
  93. See [testing](docs/specs/testing.md), [demo](docs/specs/demo.md) and the
  94. [production criteria](docs/specs/agent-criteria.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.