guild-operators: Cardano pool tooling that tells you to learn the job first

Most of the readme is a list of pre-requisites

The interesting content of this repository is not a feature list. It is the paragraph that says the guides are present to help you simplify your tasks, but that as an entity responsible for creating blocks on a financial platform, the guild expects the pre-requisite skillsets before you enter the portal.

Five of them are named. Learn about working with architecture, setup and essentials, which is sysops. Understand how to secure your server, which is secops. Be comfortable with cardano-cli and have worked on the preview, preprod or guild networks for pool operations without using wrapper scripts, described as an education exercise. Read the documentation and the disclaimers. And use an offline workflow.

The third one is the filter. Requiring someone to have run a pool on a test network with the command line tool and no scripts is a way of saying the scripts are not the learning curve. Everything else in the repository assumes that exercise already happened.

That framing is unusual and deliberate. A tool that creates blocks on a financial network has an obvious incentive to make its own on-ramp the fastest route, and this one declines to.

The disclaimer says the tools do not do everything for you

One pre-requisite is a sentence about scope: the guide and tools only aim to simplify your tasks, it will not try to do everything for you, and it does not scope best practices.

Three separate denials in one line, and each rules out a different expectation. You are not getting automation that covers the lifecycle. You are not getting a replacement for knowing how a stake pool is operated. And you are not getting an opinion on how a production pool should be configured.

The second denial matters most in practice. Wrapper scripts that abstract a chain protocol are exactly the kind of thing where the abstraction leaks at the worst time, during a slot miss or a ledger state transition, and a script layer that has quietly become the only way you know the system is a bad thing to own.

The third denial is also practical: best practices for a financial network change, and a repository that pinned itself to them would be wrong within a year. Saying so up front is cheaper than being asked later.

The keys rule is stated in capitals

The last pre-requisite is the one written as a prohibition: use an offline workflow, and never have wallet keys or pool keys made available to online servers, as supported by the tools.

Three things in that sentence. Never is the operative word, and it is the only place in the readme where emphasis is used. Online servers is qualified as the exposure rather than the internet in general, which is a narrower and more accurate danger. And as supported by the tools says the prohibition is achievable with what the repository ships, not aspirational.

In a Cardano pool the pool keys are what sign blocks and the wallet keys are what hold stake, so this is the difference between an operational mistake and a loss of funds with no recovery path. A misconfigured relay costs uptime, a leaked key costs the pool.

It is also the reason the pre-requisite list leads with securing the server. The offline workflow is the outcome of taking secops seriously, not a separate instruction, and a tool that quietly uploaded keys would make the whole list theatre.

Three documentation sites, and one of them is a placeholder

The documentation is split across three sites rather than kept in the repository, and each has a different status.

The Stake Pool Operator site holds the instructions for the guild tools, the ones that simplify setting up, managing and monitoring pools. That is the operational documentation and the reason the repository exists as more than a script dump.

The Community Support FAQ and how-to guides cover the questions a delegator or a new user actually asks, with Cardano wallets, blockchain explorers and selecting a pool for delegation named as examples. The scope is user-facing rather than operator-facing, which is why it is a separate site.

Concepts is described as a placeholder where educative articles explaining the basic essentials of blockchain can be accumulated. A placeholder is named as a placeholder here rather than presented as a finished library, and for a repository aimed at people who already run pools that gap is honest rather than odd.

The repository itself holds docs/, files/ and scripts/ at the top level, so the tooling is versioned here while the explanation lives on a site you read separately.

Default branch alpha, no releases at all

Two administrative facts shape how you should treat this repository.

The default branch is alpha, not main, and there are no GitHub releases. So there is no version to pin, no changelog to read and no artefact to download. What you clone is a working branch whose content can change under you, and the only record of what changed is the commit history.

That is consistent with the readme's own framing. The Telegram announcement and support channel is where new releases and changes to the code base are announced, which means the release announcement channel for this project is a chat channel rather than a tag. For a repository of artifacts that people run against a financial network, an announced change arriving as a Telegram message is worth pinning before you read it.

The last push is dated 29 September 2026 and the licence is MIT. The recorded primary language is Shell, which matches a repository whose payload is scripts.

Bugs take issue templates, features take discussions

The support section splits two kinds of report into two systems, which is a small sign of a functioning project.

Bugs and issues with scripts and documentation go to a GitHub issue through a URL that ends in an issue template chooser, so a report starts from a form rather than an empty box. Feature requests are asked for as a discussion thread instead. For a repository whose users are operators, that split matters: a bug report needs a reproducible environment and belongs in a tracker, while a request for a script is a conversation that may not survive being filed as a defect.

General questions go to the same Telegram channel used for announcements, so one channel carries both the news and the queue of small questions.

What the readme does not cover is the practical middle: how to run any of the scripts, which ones exist, what a healthy host looks like, or how to roll back. All of that is behind the three documentation sites, and the readme itself is the entry point rather than the manual.

Three brand files and an editorconfig in a shell repository

The top level is small: .editorconfig, .github/, .gitignore, .vscode/, LICENSE, README.md, docs/, files/, scripts/, and three image assets, guild.svg, guild_horizontal.png and guild_vertical.png.

The editor configuration is the detail that says something. A repository whose payload is shell scripts ships .editorconfig and a .vscode directory, which means the scripts are held to a whitespace and shell style rather than left to whoever edits them. That is consistent with a project whose scripts get run on other people's servers.

The three brand files are the other end of it. Two PNG orientations and one SVG exist to be embedded in documentation and on the sites, which tells you the visual identity is maintained alongside the code rather than borrowed from a parent project.

So the shipped artefacts are scripts, documentation, files and a small amount of branding, and there is no package manifest, no version file and no release workflow visible from here. The guild is the community, and the repository is the place where it contributes together.

Editorial conclusion

Read guild-operators as a set of community-run artifacts with a stated audience of people who already run stake pools, not as an onboarding path. The readme sets that boundary itself: learn the architecture, secure the server, use cardano-cli on a test network without wrapper scripts, and keep keys offline. For anyone who meets those conditions it is a genuine community contribution path, with bugs on issue templates and features on discussions. Before you rely on it, remember there are no releases and the default branch is alpha, so you are reading a working branch rather than a version, and the key handling rule is the one that protects the pool.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository