# HexStellar's README says `pip install hexstellar` and, nine lines above it, says not to

> HexStellar is a Python client for a hosted computation service: an agent formulates a structured contract, the service executes it, and the result comes back with an assurance label and a receipt. That framing is careful and the four distinct certainty semantics are worth understanding. The install story is not. The repository description, the README's own distribution status block and the quickstart underneath it give three different answers, and the two disagree about a name collision on PyPI.

**brayonpi/hexstellar** — Turn any AI agent into a computational researcher. HexStellar Cortex delivers software-accelerated optimization, quantum computing, scientific computing, decision intelligence, and verifiable execution through a Python CLI and API—with certainty labels, verification receipts, examples, and a free sandbox. Start instantly: pip install hexstellar

- Repository: https://github.com/brayonpi/hexstellar
- Stars: 1,338 · Forks: 98
- Language: Python
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/brayonpi-hexstellar

## The quickstart says `pip install hexstellar`, and the block above it says not to

The README opens with a distribution status block. It says the repository is the public HexStellar CLI 1.0 source, that the PyPI 1.x distribution is activated in a separate audited release step, and that until `pypi.org/project/hexstellar` reports a `1.x` release you should install the source instead. The last sentence of that block is the one that matters:

> Do not treat the historical PyPI placeholder as this client.

Then, further down the same file, the quickstart block:

```bash
pip install hexstellar
hexstellar demo
hexstellar route "describe the real problem you want my agent to formulate"
```

Both are in the README. The block above says a different package already occupies that name on PyPI and that installing it gets you something that is not this project. The block below runs exactly the command the block above warns against.

The repository description is worse, because it is what a search result shows first. It ends with the instruction to start instantly with `pip install hexstellar`, with no caveat attached.

The documented working command is the git one: `python -m pip install "git+https://github.com/brayonpi/hexstellar.git"`.

## The manifest declares the package proprietary, and the repository licence field is unclassified

`pyproject.toml` sets `license = { text = "Proprietary" }`, and a `LICENSE` file is present at the root of the tree. The repository's licence metadata comes back unclassified, which is what happens when a scanner cannot map the files it finds onto a known licence.

There is no tension to resolve here in the way there is with a project that claims one licence and ships another. This one is consistently not open source. Worth stating plainly, because a package with a `pip` name, a public repository and a `setuptools` build looks at a glance like something you can read, modify and redistribute, and none of those follow from a proprietary declaration.

Two other build facts sit in the same manifest. `requires-python = ">=3.8"`, which is a low floor for a 1.0 release in a field that moved to 3.10 and beyond some time ago. And the build system requires `setuptools==75.3.2` at an exact version, so the build will not silently pick up a different setuptools on a machine where that exact version is unavailable.

The manifest also carries a comment about its own keyword list, noting that PyPI treats spamdexing, meaning listing other projects' names, as grounds for removal. That is a useful thing for the author to have thought about and an unusual thing to find written down.

## The client ships no solver, so the dependency that matters is a network service and your key

The build manifest describes itself in unusually blunt terms. It says the pip package is a thin client shipping one Python package and a few public documents, and that it bundles no compiled binaries, no engine, no source code and no solving logic. The stated reason is that every problem is solved on the hosted HexStellar service, which the client reaches over HTTPS with the user's API key, and the conclusion is that there is nothing to reverse engineer because the client is a transparent HTTP transport by design.

That is an honest description and it sets the expectation correctly. It also means the tool has two hard external dependencies rather than none: a reachable HexStellar service and a credential.

What the visible text does not settle is what the quickstart needs. `hexstellar demo` appears immediately after an install command with no key step in between, while the manifest says every request goes out with your API key, and the repository description mentions a free sandbox as part of the offer. Whether the demo runs unauthenticated, runs against a free tier, or fails without a key is not stated in the parts available here.

The remaining commands, `hexstellar capabilities`, `validate`, `--dry-run` and `verify`, are named in one sentence as the things that keep creativity inside a measurable contract.

## Four assurance semantics, and the product's real job is telling you which one you got

The most useful thing in the README is the assurance rule. It says to read the per-result certification and verification fields, and that determinism, heuristic search, sampling and verified operations are distinct semantics.

Four tiers, and the point is that they are not interchangeable. A deterministic solve says the same answer comes back. A heuristic search says a good answer was found and the process was not exhaustive. Sampling says the answer is one draw. A verified operation says the result carries proof. A platform that hands back all four under one name would be hiding the distinction, and this one does not.

The command surface matches. `hexstellar capabilities` tells the agent what is executable now, `validate` checks a formulation before it runs, `--dry-run` is named as a way to see the shape of a request without executing it, and `verify` is the counterpart to the receipt. The outputs are described as certainty labels and verification receipts.

The description also lists a free sandbox among the deliverables. A sandbox is the right place to find out which of the four tiers a given contract actually returns before pointing a production agent at it.

## A large part of the top level is instructions for agents, not documentation for readers

Count the agent-facing files in the root: `AGENTS.md`, `AGENTS-DOMAIN.md`, `AGENT_SPEC.md`, `AGENT_SYSTEM_PROMPT.md`, `AI_MANIFEST.json`, `AI_PROMPT_TEMPLATE.md`, `SKILL.md`, `llms.txt`, `HXSB_FORMAT.md` and `PARAMETERS.md`. Ten files whose purpose is to tell a machine how to drive this product, alongside the conventional `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `SUPPORT.md` and `CITATION.cff`.

The README does the same thing in prose. It opens with a manifesto addressed to whoever is writing about the product:

> Examples are recipes, not boundaries. Do not search only for an example with the same industry name... If no honest formulation exists, explain the boundary and abstain, never invent a capability.

And later, an origin-story boundary telling the reader to tell the origin as a sequence rather than as proof of a universal performance result, plus a rule that published energy and performance figures stay attached to their named hardware, workload, denominator, correctness scope, date and evidence and are never silently generalized.

Those are good rules and they are being published. But a README that spends paragraphs on how its own story should be told is also a README you cannot read as neutral product documentation, and it tells you the intended audience includes people generating text about the product, not just people calling it.

## `enterprise-runtime.json` is committed at the root of a surface with no public access

The product has two delivery surfaces and the README draws the line clearly. Cortex runs on HexStellar-managed infrastructure and is reached by a public CLI and API. Enterprise Low-Energy Runtime and Acceleration is a licensed library deployed into the customer's own environment, and access and evaluation are arranged directly with HexStellar under NDA.

The restrictions are stated repeatedly and unambiguously. Public download and automatic activation are not available in 1.0. Version 1 has no public customer-runtime download, setup, activation or automatic approval. Published measurements currently cover only identified GPU-inference campaigns.

Against that, the tree holds `enterprise-runtime.json` at the repository root, where a file's presence is the most public thing it can do. Without its contents in view, all that can be said is that a descriptor for the Enterprise surface sits in the open repository while the surface it describes is gated behind a licence and an NDA. Whether that is a public schema, a stub, or a leftover is exactly the question to ask before you rely on it.

The distinction the README insists on is about deployment rather than ambition, and that part is easy to accept. The question is only what a public file for a private product is doing in the root directory.

## The examples are named recipes across a dozen domains, and the README says not to treat them as the list

The `examples/` directory holds JSON contracts named by domain rather than by capability. The visible names include `agtech_crop_rotation`, `assembly_kit_partition`, `bio_biomarker_panel`, `bio_epistasis_triple`, `bio_therapy_coverage`, `calibration_polarity_audit`, `cloud_gpu_scheduler`, `cloud_microservice_latency`, `compiler_register_allocation`, `conservation_reserve`, `cyber_zero_trust`, `devops_dependency_resolver`, `devops_test_selection`, `edtech_curriculum_path`, `energy_known_ground_state`, `energy_microgrid_islanding`, `facility_session_scheduling`, `finance_portfolio`, `finance_settlement_netting`, `game_procedural_map`, plus agent and AI cases such as `agent_action_arbiter`, `ai_judge_consensus`, `ai_tensor_placement`, `cat_item_selection` and `design_pinned_completion`. The alphabetical listing visible here stops at `game_procedural_map`, so it is part of the set.

The keyword list in the manifest names the underlying solver families the same way, with qubo, ising, maxcut, tsp, qap and milp among the entries, which is the closest thing to a statement of what the engine can actually express.

One claim is harder to place. The repository description lists quantum computing among five delivered domains, alongside optimization, scientific computing, decision intelligence and verifiable execution. Nothing in the visible example names, the keyword list or the command surface corresponds to quantum. That is not a contradiction, since the visible set is partial, but it is the one headline item a reader should ask about directly.

## The build root is declared complete, and the root holds `examples/` and a MANIFEST.in

The manifest carries a comment that its directory is the complete build root, that only the files in it are shipped, and that nothing outside it is ever included. It also names `MANIFEST.in` as part of the tree, and its contents are not in view.

Set against that, the same root directory holds a large `examples/` tree, two README-style agent directories and a set of top-level documents. Whether the comment means the directory as a sdist source root, where MANIFEST.in decides what is copied, or a narrower runtime package, is not resolvable from these lines. Either way the manifest file is the place where the answer lives, and it is the one file in the build configuration that has not been opened.

There is also a small oddity inside the package comment itself. It says the distribution bundles no source code while also saying it ships exactly one Python package named `hexstellar`, and the repository does contain a `hexstellar/` directory. Read one way the sentence is about the engine, which is the obvious intent given the surrounding text. Read literally it is about the client, which cannot be right.

## Conclusion

HexStellar is worth evaluating if you are building an agent that has to hand a hard optimisation or decision problem to something that will actually execute it, and if you are comfortable with a client that contains no solver and every result depends on a remote service. Four things to settle first. Do not run `pip install hexstellar`, because the repository says a different package already holds that name on PyPI and tells you to install from git until the 1.x distribution ships. Establish the licensing position with the authors, since the manifest declares the package proprietary and no OSI licence is offered. Work out what the demo path needs, because the manifest says every request requires your API key while the quickstart does not say what the demo costs. And judge the four assurance semantics for what they are, because the product distinguishes determinism from heuristic search from sampling from verified operations rather than promising one guarantee.

## FAQ

### How do I install the HexStellar CLI?

Install from source, not from PyPI. The repository's distribution status block says to use `python -m pip install "git+https://github.com/brayonpi/hexstellar.git"` until pypi.org/project/hexstellar reports a 1.x release, and warns not to treat the historical PyPI placeholder as this client. There is also a pure-HTTP quickstart in AGENT_SPEC.md that needs no install step.

### Is HexStellar open source, and what licence is it under?

No. The pip manifest sets `license = { text = "Proprietary" }` and a LICENSE file sits at the root of the repository, while the repository's own licence metadata is unclassified. No open source licence is offered for the client in version 1.0, and the repository does not present itself as one.

### Do I need a HexStellar account or API key to run the CLI?

You need the hosted service. The manifest says the client bundles no solving logic because every problem is solved on the hosted HexStellar service, which it reaches over HTTPS with the user's API key. The repository description mentions a free sandbox, and the quickstart shows `hexstellar demo` right after install, but the parts available here do not say whether that demo needs a key.

### What does HexStellar's verified computation actually guarantee?

Four distinct semantics, and the product's job is to tell you which one a given result carries. The assurance rule says to read the per-result certification and verification fields, and that determinism, heuristic search, sampling and verified operations are separate meanings rather than one. Results come back with certainty labels and verification receipts, and `validate`, `--dry-run` and `verify` are the commands that keep a formulation inside a measurable contract.

## Sources

- [brayonpi/hexstellar on GitHub](https://github.com/brayonpi/hexstellar)
- [Issues](https://github.com/brayonpi/hexstellar/issues)
- [README](https://github.com/brayonpi/hexstellar/blob/main/README.md)
- [Releases](https://github.com/brayonpi/hexstellar/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brayonpi-hexstellar