# Constellation and the idea that an AI plan should arrive with its own proof > Constellation is a Python mission control demo for a simulated orbital compute network, built so that a Gemini-produced plan, a planner's schedule and an independent Python checker are three separate things. The interesting part is the tamper seal: a sandbox update only proceeds if the mission version and three fingerprints still match. **brayonpi/constellation-gemini** — Proof carrying orbital mission control with Gemini, HexStellar Cortex, and independent verification - Repository: https://github.com/brayonpi/constellation-gemini - Stars: 652 · Forks: 16 - Language: Python - License: Apache-2.0 - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/brayonpi-constellation-gemini ## Three roles, none of which can approve its own work Constellation asks a narrow question: when an orbital compute network breaks, can AI create a replacement schedule without quietly breaking another rule? The demo splits the job into three parts and the split is the whole point. Gemini turns the operator's words into a checklist, identifying required work, deadlines, failed hardware and the one priority that needs human clarification. HexStellar Cortex compares complete recovery plans, searching combinations of schedule pieces while respecting the formal contract. And a separate Python program checks the answer minute by minute, so that if a job is missed, a station is double-booked, a deadline is late or failed hardware is used, the plan cannot update the sandbox. The README states the consequence plainly: no system grades its own homework. Gemini cannot approve its proposal, Cortex cannot change the mission, and the independent checker only releases the exact plan it checked. The motivation section explains why this matters. An AI generated plan can sound convincing while hiding a small but serious mistake. One contact can overlap another, a job can finish after its deadline, a failed computer can accidentally reappear. Those mistakes are hard to spot in prose and easy to find when the plan becomes a testable software contract. So the deliverable is not a schedule. It is an inspectable one. A judge can watch the work happen, open the exact failure when a rule is broken, download every input and receipt, and rerun the checker without Gemini, Cortex, or an internet connection. ## The four role mental model, including the hash that gates everything The README offers a 20-second mental model with four roles, and the fourth one is the part most people would miss. Gemini 3.5 Flash is the translator. It turns an operator's sentence into a visible checklist, and it does not choose or approve the recovery schedule. Cortex is the planner. It receives a structured data puzzle made from candidate schedule pieces, required obligations, conflicts, costs, forced choices and forbidden resources, and it does not receive authority to interpret the operator's intent or mutate the mission. Python is the inspector. Independent source code replays the complete timeline and reports a concrete counterexample when a declared rule fails, and it cannot repair a candidate to make it pass. And SHA-256 is the tamper seal: the sandbox update requires the current mission version, canonical input fingerprint, plan fingerprint and verification fingerprint to match. That last role is what makes the rest more than a demo of a good idea. If the plan can be changed after verification, or the mission can be changed after verification, then the check was performed against something other than what is applied. Four fingerprints, one of which is the mission version, close that gap. The README is also honest about what verification does not cover. The verifier proves that the formalized checklist was obeyed. It cannot know that an operator meant something they never confirmed. That is why Constellation displays the extracted rules, pauses on a significant ambiguity, and changes the fingerprint whenever the accepted meaning changes. That last behaviour is the design decision worth adopting even if you never run the demo. The system refuses to silently resolve an ambiguity in the operator's intent, and it makes the resolution part of the signed state. ## Cortex gets a contract and returns an assurance label nobody promotes The section on what Cortex receives and returns is the most technical part of the README, and it explains the contract shape. A candidate schedule piece can represent a complete local sequence, such as running a job on one satellite, storing its output, and sending that output through a compatible ground station during an allowed window. Cortex selects a set of pieces under the submitted public contract. The input declares five things: work that must be covered, hardware that must not be used, choices that cannot coexist, commitments that must stay fixed, and costs such as delay and disruption. The response contains selected identifiers, coverage and violation fields, declared cost fields, the assurance Cortex actually returned, a receipt, and live operational measurements when available. The sentence that matters is the one after. Constellation never promotes that assurance label. A separate checker still recomputes the complete mission properties in the original domain. In other words, the planner's own claim about how good its answer is is passed through untouched and then independently re-derived by code that does not trust it. The README is also careful about performance claims, which is unusual and worth noting. Cortex executes supported contracts on HexStellar managed accelerated infrastructure, and a live response can report engine time and peak RSS, with those fields displayed exactly as returned. But one run is operational telemetry, not a comparative benchmark, so the project states that it does not claim a speedup multiplier, universal acceleration, or global optimality without corresponding controlled evidence. The precision claim is narrow and testable: the request is structured, constraints are explicit, the response is machine-readable, the assurance is preserved, and independent code recomputes the properties required before action. ## The satellites are simulated, the checker is not There is a section in the README devoted to what is simulated and what actually runs, and it is the first thing you should read before drawing any conclusion from the demo. The satellites, collision, stations, orbital geometry, batteries, storage and sandbox are a deterministic research scenario. The README says they explain and stress the workflow, and that they are not real spacecraft telemetry or evidence of physical flight safety. The compiler, the public Cortex adapter, the Python checker, the fingerprints, the artifacts and the apply lock are executable software. In a run labeled live, the backend submits the formal cover contract to the external Cortex HTTPS service and preserves its sanitized response and receipt. A local or fallback run is visibly labeled and is never presented as proof of a live Cortex call. That labelling requirement is the point. A system that cannot prove which mode produced a result is a system whose results you cannot reason about, and this one treats the label as part of the evidence rather than as a console message. The term independent checker is also defined precisely, and the definition is narrower than you might assume. It means separate from the planner. The verifier does not import the HexStellar client, call Cortex, call Gemini, or change the candidate. It is project-authored inspectable code, not a third-party certification. That last clause matters for how you use the project. The independence here is architectural separation within one codebase, not organisational separation. It gives you a checker that cannot be fooled by the planner's own state, which is the useful property, but it does not give you an audit by someone else, and the README does not claim it does. ## The scenario has a fixed shape, 12 satellites and 24 compute jobs The primary scenario is a deterministic software simulation with 12 satellites, four ground stations, 24 compute jobs, 36 communication windows, storage and energy limits, required health checks, and a valid starting schedule. The disruption arrives as a Pub/Sub event. One ground station is removed and two compute nodes are isolated while an urgent job arrives. Everything about this being a fixed scenario rather than a simulation of something real is deliberate, and it has a double effect. It makes the demo reproducible, which is what lets the checker be re-run and the fingerprints mean something, and it bounds what the demo can claim. The scenarios are not a model of any particular constellation's behaviour, and the README does not present them that way. The application then freezes the mission, and the README is cut off at that point, so the sequence after the freeze is not documented in the text available here. The rest of the behaviour is described in the surrounding sections: the recovery is compared, the checker runs, and the sandbox update is gated on the fingerprints. The Evidence Room is where a reviewer actually exercises this. It has a Run independent check again button that sends only the already frozen mission data to the Python verifier, and it does not call Gemini or Cortex. The same panel can display and download the exact verifier.py source shipped in the running deployment. Every new replay ZIP also includes VERIFIER-SOURCE.py, AI-REVIEW-PROMPT.md, all input and result files, and a checksum manifest, and the offline command verifies the frozen evidence package. It does not rerun Gemini or Cortex and therefore does not claim those services are deterministic. ## Running it locally is a Makefile and an environment file The project is a Python application with a FastAPI backend and a web front end, and the local setup is described by the Makefile and the.env.example file. The environment file is the interesting part, because it shows every external dependency the demo has and how each is switched off by default. The mode is local, the role is web, and the database is a SQLite file: ```bash CONSTELLATION_MODE=local CONSTELLATION_ROLE=web CONSTELLATION_DATABASE_PATH=./constellation.sqlite3 CONSTELLATION_PUBLIC_BASE_URL=http://localhost:8080 ``` The model settings are named explicitly: ```bash GEMINI_MODEL=gemini-3.5-flash HEXSTELLAR_API_URL=https://api.hexstellar.com HEXSTELLAR_API_KEY= CORTEX_MODEL=cortex-1.0 CORTEX_COVER_EFFORT=medium CORTEX_QAP_EFFORT=flash ``` So the Gemini model and the Cortex model are configurable, the Cortex effort levels are split into a cover effort and a QAP effort, and the API key is empty in the example. The remaining variables cover Google Cloud pieces, a task service account, a worker base URL, an artefact directory and bucket, CORS origins, a maximum request size of 65536 bytes, and a public run limit of 100. The Makefile targets describe the workflow, and the help text is the fastest summary of it. There are install, dev, api, web, test, lint, verify-demo, verify-bundle, audit and docker targets, and the api target runs uvicorn constellation.main:app on port 8080 with PYTHONPATH set to apps/api, while the web target runs the Vite UI. The verification targets are the ones that make the project checkable rather than merely runnable. verify-demo verifies the committed recovered mission, and verify-bundle verifies a downloaded replay ZIP, taking the path through a BUNDLE variable and refusing to run without one. ## Where Constellation is the wrong tool The first wrong case is any use that looks like flight software. The README states it directly: the satellites, collision, stations, orbital geometry, batteries, storage and sandbox are a deterministic research scenario and are not real spacecraft telemetry or evidence of physical flight safety. Anyone who takes the visualisation as a mission control interface for a real constellation has misread it. The second wrong case is a requirement for third-party assurance. The independent checker is project-authored inspectable code, and the definition of independence here is architectural, meaning it is separate from the planner and does not import the client or call the services. It is a genuine engineering property and it is not the same property as an audit by an accredited third party. A safety case that requires the latter cannot be satisfied by this project. The third is a workload that needs the external services to behave the same way twice. The offline bundle verification explicitly does not rerun Gemini or Cortex and does not claim those services are deterministic, and a replay of the same mission will therefore not necessarily produce the same plan. That is fine for a demo where the frozen evidence is the artefact, and it is a problem if your use case depends on reproducibility of the generation step rather than of the verification step. The alternative worth naming is a plain contract-checker layer over whatever planner you use, written by you, with the fingerprints you need. The difference in approach is that Constellation ships a specific ecosystem, the Gemini checklist, the HexStellar Cortex client, the Evidence Room and the replay bundle format, and it is integrated enough that the guarantee covers the whole chain. A hand written checker over your own planner gives you the same structural property, that the verifier cannot modify the candidate, with none of the specific integrations and none of the prebuilt evidence packaging. If you want the packaging, the Evidence Room and the replay ZIP because they are what make a judge able to recheck a run, this project has already built them. If you only want the separation of duties, you can write forty lines of Python and skip the rest. ## Licensing, the container and the state of the project The project is Apache-2.0 licensed, with the LICENSE file at the repository root, and the pyproject manifest records the licence the same way. There is also a NOTICE file and a THIRD_PARTY_NOTICES.md at the top level, alongside a CONTRIBUTING.md and an AI_REVIEW_GUIDE.md. The build system is hatchling, the package is named constellation-mission-control at version 0.1.0, and it requires Python 3.12 or newer. The runtime dependencies are small and ordinary: FastAPI, httpx, pydantic, pydantic-settings, python-multipart and uvicorn with the standard extra. Everything Google related is behind an optional extra called google, which includes the Google ADK, Firestore, Pub/Sub, Storage, Cloud Tasks and google-genai. The dev extra carries pytest, pytest-asyncio, pytest-cov, pip-audit and ruff. That split is worth noting. The core application does not need Google Cloud to run, and the google extra exists for the parts that do, which matches the local mode in the environment file. The Dockerfile builds the web front end from node:22-alpine and then copies the built assets into a python:3.12-slim runtime image that installs the package with the google extra. It runs as a non-root user with uid 65532, sets the database path, fixture directory and web dist path as environment variables, exposes port 8080 and starts uvicorn on that port. On maintenance state, the repository is not archived and the last push was on 2026-08-31, with no GitHub releases. The project version in the manifest is 0.1.0, which is an honest signal about maturity, and the Makefile's audit target runs the release-quality tests, the front end build, npm audit and pip_audit, so the dependency scanning is part of the project's own definition of done rather than an afterthought. ## Conclusion Constellation fits an engineer who needs to convince a reviewer that an AI generated plan obeys a written contract, rather than merely reading like a good plan. It is a research demo, not flight software, and the README is explicit that the satellites, collisions and orbital geometry are a deterministic scenario rather than telemetry. Before you build on it, read the distinction between what is simulated and what actually runs, check that the model settings in your .env file match the services you have access to, and treat the local mode as the default, because that is what CONSTELLATION_MODE=local selects. ## FAQ ### What is the Constellation project? Constellation is a Python mission control demo for a simulated orbital AI constellation, described as proof-carrying mission control. It separates three roles: Gemini turns the operator's words into a checklist, HexStellar Cortex compares recovery plans under a formal contract, and an independent Python program checks the answer minute by minute. ### How does Constellation prevent an AI plan from being applied unchecked? The sandbox update requires the current mission version, the canonical input fingerprint, the plan fingerprint and the verification fingerprint to match, with SHA-256 acting as the tamper seal. If a job is missed, a station is double-booked, a deadline is late or failed hardware is used, the plan cannot update the sandbox. ### Is the Constellation simulation real spacecraft data? No. The satellites, collision, stations, orbital geometry, batteries, storage and sandbox are a deterministic research scenario, and the README says they are not real spacecraft telemetry or evidence of physical flight safety. The compiler, the Cortex adapter, the Python checker, the fingerprints and the apply lock are the parts that are real executable software. ### How do I run Constellation locally? Copy the variables from .env.example, which sets CONSTELLATION_MODE=local and leaves the model API keys empty, then use the Makefile. The api target runs uvicorn constellation.main:app on port 8080, the web target runs the Vite UI, and verify-demo and verify-bundle check the committed plan and a downloaded replay ZIP. ### What does the offline Constellation bundle verification actually prove? It verifies the frozen evidence package, and every replay ZIP includes VERIFIER-SOURCE.py, AI-REVIEW-PROMPT.md, the input and result files and a checksum manifest. It does not rerun Gemini or Cortex, so it does not claim that those services are deterministic. ## Sources - [brayonpi/constellation-gemini on GitHub](https://github.com/brayonpi/constellation-gemini) - [Issues](https://github.com/brayonpi/constellation-gemini/issues) - [License: Apache-2.0](https://github.com/brayonpi/constellation-gemini/blob/main/LICENSE) - [README](https://github.com/brayonpi/constellation-gemini/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brayonpi-constellation-gemini