Read me first

If you have just been handed Pennant and you are wondering what it is and whether it is for you, start here. This page assumes no technical background. There is no code in it and nothing you need to install before reading.

Everything below describes what the software actually does today. Where something is deliberately not included, it says so.

---

1. Who this is for

The person Pennant is built around is whoever decides when a new feature goes live. In most companies that is a product manager, a product owner, or a team lead — someone accountable for a change landing well, who is not necessarily the person who wrote it.

Two other people use it regularly:

• The engineer, who connects Pennant to the company's software and looks into why a particular customer did or did not get a feature.
• The reviewer, who is asked to approve a change to the live system, often knowing nothing about it beforehand.

It is designed for a team of roughly 5 to 50 developers — big enough that releases need coordinating, small enough that heavyweight release processes get in the way.

One deployment of Pennant serves one organisation. It is not built to host several separate companies side by side.

---

2. What it does

Pennant separates shipping code from releasing it.

Normally those happen together: code goes live, and the moment it does, everybody has it. That makes every release a gamble. If something is wrong, the only way back is another release.

Pennant puts a switch in front of each new feature. The code ships in the normal way, but the feature stays off. Then, separately and at your pace, you decide who sees it: nobody, your own staff, one customer, five percent of users, everyone. If it goes wrong, you turn it off in one action — no new release, no waiting.

On top of that it answers three further questions:

• Did it help? Run a proper comparison between the old and new behaviour and get a plain-language verdict, not just a table of statistics.
• Who has it? See uptake by individual user or by customer account.
• What can we delete? Old switches pile up and clutter the code. Pennant finds the ones that are finished and prepares the change that removes them.

---

3. The domain: feature flags, in plain terms

A feature flag (also called a feature toggle) is a named on/off switch that lives outside your software. The software asks "is this on for this person?" and behaves accordingly.

That simple idea underpins several standard practices:

• Dark launching — the feature is live but off, so you can turn it on the moment you are ready rather than scheduling a release.
• Canary or percentage rollout — give it to 1% of people, watch, then 5%, then 25%. If something breaks, it broke for very few people.
• Kill switch — the one-action off, used when something is going wrong right now.
• Entitlement — a feature that is permanently on for some customers and off for others, because of what they have bought.
• A/B test or experiment — deliberately give two groups different behaviour and measure which does better.

The reason this matters commercially: teams that release behind flags release more often and with less drama, because a bad change is a switch away from being contained rather than a rollback away.

The counterweight, and the reason section 8 exists: flags are easy to add and easy to forget. A codebase full of switches nobody has turned off in two years is harder to work in, not easier. Flags are meant to be temporary, and most teams never remove them.

---

4. Where it fits

Who your users will be. Everyone using Pennant works at your company. Your customers never see it — they only see the effects of the decisions made in it.

What it sits alongside.

• Your own software. This is the essential connection. Your application asks Pennant what is switched on. Pennant ships one official connector for server-side JavaScript and TypeScript. Every other language connects through OpenFeature, an open industry standard for feature flags — you use a standard OpenFeature client that anyone can obtain, rather than something Pennant wrote. A practical consequence: because Pennant speaks a standard, you are not locked in.
• Your sign-in system. Pennant has no accounts or passwords of its own. It takes identity from the platform it is installed on, so people sign in with the company account they already have.
• Your chat, alerting or automation tools. Pennant can send a signed message to a web address of your choosing whenever something changes, which is how teams route changes into a chat channel or an on-call system.
• Your build and deploy pipeline. Everything that can be done on screen can also be done programmatically, so flag changes can form part of an automated process.

What it deliberately does not do. It does not host multiple separate companies. It does not store flags in a Git repository, run at CDN edge locations, replay user sessions, do product analytics, or decide by itself to roll something back. It does not work out someone's country from their network address — if you want to target by geography, your software tells Pennant the country.

---

5. Your first run

Do the smallest possible real thing, end to end. Create one flag, connect one application to it, and turn it on and off while watching the application respond.

Concretely:

1. Sign in. You will arrive at a list of projects. A project is one piece of software; each gets a development, a staging and a production environment automatically.
2. Create a flag with a name that says what it controls.
3. Go to Credentials and issue a key for the development environment. It is shown once and never again, so put it somewhere safe immediately.
4. Give that key to whoever is connecting your application, and have them ask Pennant about your new flag in one place in the software.
5. Turn the flag on and off and watch the behaviour change.

Do not begin by modelling every flag you think you will need. The first loop working end to end is worth more than a tidy list of switches nothing is asking about.

---

6. Setting up properly

Once the first loop works, build out in this order.

Decide who is in. Add your colleagues under Members and give each a role (section 11). Adding people early matters, because production changes may need a second person to approve them, and a project with only one approver cannot demonstrate that.

Protect production. Production is protected by default. Editing a flag's configuration there — its targeting, its rules, its default — does not take effect when you save it; it becomes a request that somebody else has to approve. Leave it that way.

There is one deliberate exception, and it only runs one way: turning a flag off is always immediate, in every environment, with no approval step. That is what makes an emergency off possible during an incident, and it is why the off control is never harder to reach than the on control. Turning a flag on in production is an ordinary production change and waits for a reviewer like any other.

Connect your application properly. Each environment gets its own key. A development key cannot read or change production, which is the point. Your software then evaluates flags locally against a copy of the configuration it keeps up to date, so asking "is this on?" costs nothing and does not depend on Pennant being reachable at that instant.

Describe your users. Decide what your software will tell Pennant about whoever it is serving — a plan, a country, an account, a version. Targeting can only use facts you send. There is no separate upload step and no import of a customer list: the attributes arrive with each request from your software.

Name the audiences you will reuse. If "internal staff" or "EU enterprise customers" appears on more than one flag, create it once as a segment and point flags at it.

Set up notifications if you want changes to reach a chat channel or an on-call tool.

---

7. Day to day

Most days involve some of the following.

Starting a rollout. Create the flag, keep it off, let the code ship. When ready, turn it on in development, then staging, then production — promoting a flag shows you exactly what will change before it applies.

Raising a percentage. Move from 5% to 25% to 100% over days. Anyone already in the group stays in it; raising the percentage never reshuffles the people who already had it.

Answering "why did this customer see that?" Use the evaluation inspector on the flag's page: describe a user and it tells you which rule decided and why.

Handling an incident. Find the flag, strike it. One action, no confirmation step, no waiting for approval. Then look at the history to see what changed and when.

Reviewing someone's change. Requests wait in Approvals. The review screen shows what would change against production as it stands right now, so a stale request cannot be approved on the basis of how things looked last week. You cannot approve your own.

Reading a result. An experiment leads with a sentence saying what happened and what it means. "No clear difference" is a real, useful answer and is reported as such rather than dressed up.

---

8. Ongoing care

Clean up finished flags. This is the task everyone skips. Pennant scores each flag for staleness using its age, whether anything still asks about it, whether everyone now gets the same answer, and whether the code still mentions it — and it tells you which of those reasons applied. It can prepare the change that removes a flag and tidies the code around it. It never applies that change by itself; a person reviews it.

Give flags an expected lifetime when you create them. Pennant tells you when one outlives it. A flag meant to last two weeks and still live at six months is the thing you want flagged.

Watch your rate limits if automated systems talk to Pennant. Requests over the limit are refused with guidance on when to retry, never dropped silently — and never in a way that breaks flag evaluation in your application.

Understand what is kept. Change history is kept indefinitely. Evaluation statistics get coarser with age: detailed for at least 30 days, hourly for at least 90, then daily indefinitely. Raw experiment measurements are removed no sooner than 30 days after the experiment finishes.

Back up the database. Pennant needs one database, and that database holds everything: flags, history, experiments and members. Whoever runs your infrastructure should back it up on the same schedule as any other system of record. The cache Pennant can also use is disposable by design — losing it costs speed, never correctness.

---

9. A short glossary

Term	What it means here
Project	One piece of software. Holds its own flags, segments and members.
Environment	A stage of a project — development, staging, production. Each holds its own state for every flag.
Flag	The named switch. Can be on/off, or carry a word, a number or a structured value.
Variant	One of the named values a flag can serve, such as "on" and "off".
Targeting rule	A condition deciding who gets which variant. Tried in order; first match wins.
Segment	A named, reusable audience that many flags can point at.
Override	A decision for one named individual or account that beats every rule.
Rollout percentage	The share of people getting the new variant. Assignment is stable.
Strike / kill switch	Turning a flag off immediately for everyone in one environment.
Promotion	Copying a flag's configuration from one environment to the next.
Experiment	A measured comparison between variants, with a verdict.
Guardrail	A metric watched for harm during an experiment, separate from what you are trying to improve.
Account	A customer organisation, targetable in its own right, so all its users get the same answer.
Credential	A key letting one application talk to one environment. Shown once.
Stale flag	A flag that appears finished and is a candidate for removal.
OpenFeature	The open industry standard Pennant speaks, so non-JavaScript languages can connect with standard tools.

---

10. The other documents here

• user-docs/production-initialization.md — for whoever stands up a real system. Covers the one command that prepares a brand-new database for first use, and the safeguards around it, because that command erases the target database.
• preview/README.md — how to build and run the all-in-one evaluation image described in section 12.
• collateral/user-guide/plain-english-guide.md — a longer non-technical guide.
• collateral/user-guide/complete-user-guide.md — the full guide, feature by feature.
• collateral/technical/ — for engineers doing the integration.
• collateral/install/ — installation and integration instructions.

---

11. Who can do what

Four roles, from most to least powerful:

Role	Can do
Owner	Everything, including managing members and their roles.
Admin	Everything operational: flags, segments, experiments, credentials, approvals.
Member	Day-to-day flag and segment work, and proposing changes to protected environments.
Viewer	Read-only. Can see everything, change nothing.

Two rules hold regardless of role: nobody approves their own change to a protected environment, and a credential only ever reaches the single environment it was issued for.

---

12. The sample data, and starting clean

The all-in-one evaluation image arrives with a fictional company already set up — projects, flags in various states, segments, finished and running experiments, approval requests, history and customer accounts. None of it is real. It exists so every screen has something on it, because an empty product tells you nothing about how it behaves.

Explore it freely. It is a throwaway copy that lives inside the running container: stop the container and the changes are gone, and starting it again gives you the same clean sample. Nothing you do reaches anything real.

When you want a genuine, empty system, that is a different path — a separate command that wipes the target database and loads only the minimum needed to start. It is described in user-docs/production-initialization.md. Read the safeguards first.

---

13. Questions people ask early

Is this a deployment tool? No. Your existing process still ships the code. Pennant decides who the shipped code behaves differently for.

What if Pennant goes down? Your application keeps working. It evaluates flags from the configuration it already holds, and if it cannot reach Pennant at all it falls back to the default value your code supplies. Flags fail to a default, not to an outage.

Does checking a flag slow my software down? No. Your application answers from a copy it already has in memory, with no network call for each check.

Can I use it from Python, Go, Java, Ruby? Yes, through OpenFeature. There is one official Pennant connector, for server-side JavaScript and TypeScript; everything else uses standard OpenFeature clients Pennant did not write. Do not expect a suite of Pennant-branded connectors — there is deliberately one.

Can two teams keep their flags separate? Yes, as separate projects with their own members. But one Pennant serves one organisation; it is not built to host several companies.

Why can't I approve my own change? Because an approval that the author can grant themselves is not a control. If a project genuinely has only one approver, changes are applied directly and recorded as having had no independent review — visible rather than disguised.

Do I have to use the AI features? No. Every one of them has a manual path, and when assistance is switched off the screen says so and points to the manual route. Nothing becomes unavailable.

How new is this? New. It has no customers yet, no production track record, and no certifications. What it does have is its specification and an automated test suite that is run on every change. Anyone claiming otherwise is overselling it.

---

14. Where to get help

Pennant was built as part of the worlds-biggest-software-project initiative, and its community is the place to go: wbsp.ai.

Go there to ask questions, suggest something it should do, find people who can adapt it to your business, or look at what others have built — including other versions of this same application that may already be closer to what you need.

What you have been given is the core: the functionality, without any company's branding on it. It is meant to be taken and made yours.