Documentation

Pennant

Self-hosted feature flags and runtime configuration.

Pennant stores feature flags and runtime config and serves them to your applications over a small HTTP API. Flags change instantly — no redeploy — and a streaming endpoint pushes updates to connected clients.

Flags are scoped to environments. The same flag can be off in production, on in staging, and rolled out to a slice of users, all from one place.

#Installation

Pennant ships as one static binary. Place it on your host and start it:

# download and start
$ curl -sSL get.stanislav.net/install | sh
$ pennant serve --data /var/lib/pennant
→ listening on :4800 · api ready

By default Pennant binds to 127.0.0.1:4800. Put it behind your own reverse proxy to expose it over TLS.

#Quickstart

# create a flag
$ curl -X PUT :4800/v1/flags/new-ui \
    -d '{"rollout":25}'
→ ok

# evaluate it
$ curl ':4800/v1/eval/new-ui?user=42'
{"enabled":true}

#Configuration

Configure with flags, environment variables, or a small YAML file. Flags take precedence.

# pennant.yaml
data:    /var/lib/pennant
listen:  127.0.0.1:4800
log:     info
environments:
  - production
  - staging

data — directory where flags and rules are stored.
listen — address the HTTP interface binds to.
environments — the environments flags can be scoped to.

#API reference

Every route lives under /v1. Requests without a valid token return 401.

Method & path	Description
`PUT /v1/flags/{name}`	Create or update a flag.
`GET /v1/eval/{name}`	Evaluate a flag for a context.
`GET /v1/flags/_stream`	Stream flag changes to a client.
`DELETE /v1/flags/{name}`	Remove a flag.
`GET /health`	Liveness probe. Returns 200 when ready.

#CLI

The pennant binary is both the server and the client.

Command	Description
`pennant serve`	Start the server.
`pennant flags ls`	List flags.
`pennant set <flag> <value>`	Set a flag value.
`pennant status`	Show connected clients and flag counts.