> 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/basic-concepts/runtime-sdk.md).

# Runtime SDK

The Govplane Runtime SDK is a **policy engine that runs inside your process**. It holds a verified policy bundle in memory and answers every decision locally — synchronously, with no network call on the request path.

```
┌──────────────────────────────────────────────────────────────────────┐
│                          Your Application                            │
│                                                                      │
│   govplane.evaluate({ target, context })                             │
│            │                                                         │
│            ▼                                                         │
│   ┌──────────────────┐         ┌──────────────────────────────────┐  │
│   │   Policy Engine  │◄────────│           Bundle Source          │  │
│   │   (in-process)   │  bundle │                                  │  │
│   └────────┬─────────┘         │   local  → a file on disk        │  │
│            │                   │   remote → Govplane Cloud        │  │
│            ▼                   └──────────────────────────────────┘  │
│      Decision                                                        │
│      allow · deny · throttle · kill_switch · custom                  │
└──────────────────────────────────────────────────────────────────────┘
```

Evaluation never leaves the process. The context you pass — who is asking, what they are asking for — is read by the engine and discarded. It is not transmitted, not logged by the SDK, and not present in traces.

### Two ways in

Every SDK offers the same two sources, and they produce the same client.

|                      | **Local**                                             | **Remote**          |
| -------------------- | ----------------------------------------------------- | ------------------- |
| Bundle comes from    | a file on disk                                        | Govplane Cloud      |
| Needs an account     | no                                                    | yes                 |
| Needs a runtime key  | no                                                    | yes                 |
| Needs network access | never                                                 | to poll for updates |
| Updates              | when the file changes (if watch option is configured) | by polling          |

**Local is the whole product, not a degraded mode.** Build a bundle with the CLI, sign it, ship it the way you ship configuration, and point the SDK at it. Nothing in that path touches Govplane infrastructure — at build time or at runtime.

Remote adds *delivery*: polling, ETag revalidation, backoff and degraded-state reporting. It does not add trust — verification is the same code either way.

{% hint style="info" %}
This is a deliberate architectural guarantee. Policy evaluation must never depend on a vendor being reachable, so the runtime is free, open, and complete without one. See Bundles.
{% endhint %}

### Available SDKs

| Language                 | Package                                                       | Status                                                   |
| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------- |
| **Node.js / TypeScript** | `@govplane/runtime-sdk`                                       | <mark style="color:$primary;">**Available — 2.x**</mark> |
| Java                     | —                                                             | Planned                                                  |
| **Python**               | [Github Repo](https://github.com/Govplane/python-runtime-sdk) | <mark style="color:$primary;">**Available — 2.x**</mark> |
| PHP                      | —                                                             | Planned                                                  |

Java and PHP implementations exist against the 1.x architecture and are being rebuilt on the 2.x model described here. **Node.js is still the reference implementation**, and this section documents it.

### Shared capabilities

Every implementation is expected to provide the same behaviour. The engine's semantics are part of the contract — a bundle must produce the same decision in every language.

**Client lifecycle**

* The first bundle is loaded and verified **before** the client exists, so there is no window in which evaluation has nothing to evaluate against.
* `reload()` re-reads the source on demand.
* `close()` releases the watcher or poller.
* A failed reload never replaces a good bundle: the previous one stays in force and an error handler is called.

**Evaluation**

* Evaluate by **target** — service, resource and action, matched exactly.
* Evaluate by **rule name**, for call sites that already know which rule they mean.
* Fixed effect precedence: `kill_switch > deny > throttle > allow > custom`, then priority descending, then `policyKey` and `ruleId` alphabetically.
* Deny by default when nothing applies. The engine never fails open.

**Decisions**

| Effect        | Meaning                                               |
| ------------- | ----------------------------------------------------- |
| `allow`       | Permitted                                             |
| `deny`        | Refused                                               |
| `kill_switch` | Hard stop, outranks everything                        |
| `throttle`    | Permitted within a limit your infrastructure enforces |
| `custom`      | An arbitrary payload defined by the policy author     |

See Effects for each in detail.

**Verification**

* Bundles are checksummed and signed over a canonical projection, so re-versioning a bundle does not invalidate its signature.
* `ECDSA_SHA_256` everywhere; `HMAC_SHA256` for bundles you signed yourself.
* An unsigned bundle, or a signed one with no key configured, is refused unless you opt in explicitly.

**Observability**

* Decision traces at four levels — `off`, `errors`, `sampled`, `full` — with sampling and per-window budgets.
* Traces carry rule identifiers, priorities and outcomes. **They never carry context values.**

### Authentication

Only the **remote** source authenticates. It uses a runtime key:

```
GOVPLANE_RUNTIME_KEY=gprk_…
```

Store it in an environment variable or a secret manager, never in source control, and treat it like a database credential — it grants read access to your compiled policy bundles.

A local client asks for no credential at all, which is the point.

### Where to go next

* [Node.js — Installation & Quick Start](/docs/documentation/sdk-for-javascript-node.js/installation-and-quick-start.md)
* [Policy Bundle Schema](/docs/documentation/schemas/policy-bundle.md) — the document the SDK loads


---

# 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/basic-concepts/runtime-sdk.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.