> For the complete documentation index, see [llms.txt](https://govplane.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://govplane.gitbook.io/docs/documentation/readme.md).

# Welcome to Govplane

Govplane is the control plane for **application governance** — a way to define, enforce and audit how your application behaves, across every environment, without scattering the decisions through your source code.

The `if` statements that decide who may do what, which feature is on, when to shed load and when to stop a service become a **policy bundle**: a signed, versioned document your application evaluates locally, in-process, in microseconds.

```ts
const decision = govplane.evaluate({
  target:  { service: 'auth', resource: 'login', action: 'authenticate' },
  context: { failedAttempts },
});

if (decision.decision === 'deny') return lockAccount();
```

Changing the threshold is a new bundle, not a release.

{% hint style="success" %}
**New here?** The [Quickstart](/docs/documentation/getting-started/quickstart.md) takes you from nothing to a signed bundle your application evaluates, in about five minutes.
{% endhint %}

***

### What changed in v2.0

**Govplane used to be a SaaS product, and almost all of it was closed.** v2.0 opens the runtime and the tooling.

This was not a license change bolted onto the same product. It required rebuilding the parts that quietly depended on us.

#### The problem we had

Policy *evaluation* was always local — decisions were made inside your process, never by calling our servers. But that was only half of independence:

* **You needed our web interface** to generate, sign and distribute bundles, and to validate schemas and syntax.
* **You needed a valid runtime endpoint** to activate the SDK at all. A hard dependency on our servers, on the startup path.
* **Everything was subscription-based.** Workarounds existed, but the shape of the product said *you need us* — and if we went away, so did your ability to ship a policy change.

That is a bad deal for anyone whose production behavior depends on it.

#### What we did about it

|                         | Before (1.x)                | Now (v2.0)                         |
| ----------------------- | --------------------------- | ---------------------------------- |
| Evaluate policies       | local                       | local                              |
| **Build a bundle**      | our web interface           | `govplane build`, on your machine  |
| **Sign a bundle**       | our signing service         | `govplane sign`, with your own key |
| **Validate a document** | our web interface           | `govplane validate`, offline       |
| **Start the SDK**       | required a runtime endpoint | reads a file; no endpoint, no key  |
| **Licence**             | proprietary, subscription   | **MIT**, on GitHub and npm         |
| Distribute a bundle     | through us                  | however you ship configuration     |

Everything in that right-hand column runs with **no Govplane account, no credentials and no network access**. Not as a fallback or a degraded mode — as the normal way to use it.

We removed the last thing tying local evaluation to a Govplane account: `orgId` and `projectId` are now optional, because a bundle you built yourself has no reason to carry our addressing scheme.

#### What stayed commercial

**Govplane Cloud** — centralised policy management, remote publishing, RBAC, observability, alerts, audit history, team collaboration and AI-assisted policy generation.

Cloud builds *on top of* the open runtime. It is not required for production policy evaluation, and it never will be. If you stop paying, your bundles keep working and your CLI keeps building new ones.

***

### The pieces

|                    | Package                 | Licence    | Cost                      |
| ------------------ | ----------------------- | ---------- | ------------------------- |
| **SDK**            | `@govplane/runtime-sdk` | MIT        | Free                      |
| **CLI**            | `@govplane/cli`         | MIT        | Free, no registration     |
| **CLI Toolkit**    | `@govplane/cli-toolkit` | MIT        | Free, one-time activation |
| **Govplane Cloud** | —                       | Commercial | Subscription              |

**The SDK** evaluates bundles inside your application. Zero runtime dependencies. It loads a bundle from a file — or, if you want it, from Govplane Cloud.

**The CLI** reads and verifies: `validate`, `inspect`. Zero dependencies, no account, and no network path at all — you can drop it into a CI job that checks a bundle without registering for anything.

**The CLI Toolkit** writes: `analyze`, `policies`, `build`, `sign`, `simulate`. Activation is free and asks for an email address in your browser — nothing else. After that the toolkit **never contacts Govplane again**: no licence check, no heartbeat, no telemetry. The licence is verified offline against a key shipped in the package, so an air-gapped machine can never lose access.

***

### What v2.0 brings

**A single way in.** `createLocalClient` and `createRemoteClient` replace the old `RuntimeClient` and its isolated-mode configuration. "Isolated mode" is gone as a concept — a local bundle is not a fallback you switch into when we are unreachable, it is a source you choose.

**No unready state.** The bundle is loaded and verified *before* the client exists, so `evaluate()` can never be called against nothing. There is no `start()`, no `warmStart()`, and no `hasValidBundle` to check.

**Signatures that verify what is actually signed.** The 1.x SDK verified bytes nobody was signing. v2 verifies the canonical projection the CLI and the control plane actually sign — checked against shared fixtures. Re-versioning a bundle no longer invalidates its signature.

**Verification is not optional by accident.** An unsigned bundle — or a signed one with no key configured — is refused unless you write `allowUnsigned: true`. Silently treating an unverifiable signature as valid would be the most dangerous possible default.

**Deterministic builds.** The same draft produces byte-identical output, so a bundle can be reproduced, diffed and audited.

**Simulation on the real engine.** `govplane simulate` runs the SDK's engine, not a reimplementation of it, so what you check before shipping is what your application gets.

**Static analysis.** `govplane analyze` finds the `evaluate()` calls in your source and writes reviewable drafts — and never invents a rule, because deciding the answer is your job.

**Modern packaging.** One ESM build that `require()` also loads, so there is no dual-package hazard and `instanceof` on the SDK's errors always works. Node.js 20.19+.

**In the 2.x line since:** evaluating a rule by name instead of by target, and shorter return shapes — `asBoolean`, `asBinary`, `effectOnly` — for call sites that only branch on the outcome.

***

### Start here

|                                                                                       |                                              |
| ------------------------------------------------------------------------------------- | -------------------------------------------- |
| [**Quickstart**](/docs/documentation/getting-started/quickstart.md)                   | From nothing to a signed bundle, \~5 minutes |
| [Policies and Rules](/docs/documentation/basic-concepts/policies-and-rules.md)        | The concepts                                 |
| [Evaluation](/docs/documentation/basic-concepts/evaluation.md)                        | How a decision is reached                    |
| [Effects](/docs/documentation/basic-concepts/effects.md)                              | allow, deny, throttle, kill switch, custom   |
| [CLI Overview](/docs/documentation/cli/overview.md)                                   | The two command-line packages                |
| [SDK Overview](/docs/documentation/basic-concepts/runtime-sdk.md)                     | Evaluating bundles in your application       |
| [A Practical Example](/docs/documentation/cli/practical-example-from-start-to-end.md) | The whole loop, thoroughly                   |

{% hint style="info" %}
The Node.js SDK is the reference implementation and the one documented here. **Java, Python and PHP are being rebuilt on this architecture.** The bundle format is language-neutral — everything you author with the CLI works unchanged when they land.
{% endhint %}

***

### What we are promising

1. **Own your runtime.** Runtime execution belongs to you. It must keep working with no dependency on Govplane infrastructure.
2. **No mandatory vendor lock-in.** You can use the SDK and hand-managed bundles indefinitely. That path is supported, not merely tolerated.
3. **Open runtime, open-source tools, premium productivity.** The runtime stays open. Advanced tooling and cloud capabilities add value on top.
4. **Cloud by choice.** Adopt Govplane Cloud because it improves your workflow, never because production requires it.

The test we hold ourselves to: **if Govplane disappeared tomorrow, could you still build, sign, distribute and evaluate your policies?** As of v2.0, yes — and that is the point.

***

### Source

* [`Govplane/govplane-runtime-sdk`](https://github.com/Govplane/govplane-runtime-sdk)
* [`Govplane/govplane-cli`](https://github.com/Govplane/govplane-cli)
* [`Govplane/govplane-cli-toolkit`](https://github.com/Govplane/govplane-cli-toolkit)

All MIT, and the source is public so you can read exactly what runs in your application — which matters for a library that decides who may do what.

Contributions and bug reports are welcome; see each repository's `CONTRIBUTING.md` first. The one exception is the SDK's Govplane Cloud client — `createRemoteClient`, authentication and telemetry — where a pull request has a high chance of being rejected even when it is correct, because the other half of that contract is closed and on its own release schedule. Open an issue there before writing code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.