Introduction

Rune is an open-source, local-first secrets manager. It encrypts your secrets, keeps them sealed until you say otherwise, and hands them out to exactly the tokens you allow — from a CLI, a Web UI, an HTTP API or straight into a Spring Boot app.

The components

Why Rune?

Most teams don't need a secrets platform. They need somewhere better than .env files, Slack DMs and CI variables nobody remembers setting. Rune is a single pair of binaries you can run on a laptop or a VM:

• Encrypted by default. Every secret is encrypted with AES-256-GCM before it touches disk.
• Sealed by default. The encryption key only lives in memory after you unseal with your passphrase.
• Least privilege. Tokens get read, write, delete and rotate per namespace — nothing more.
• History you can trust. Rotations create new versions; old ones stay encrypted and fetchable.
• Boring infrastructure. One embedded database file. No cluster, no consensus protocol, no ops team.

Quickstart

From zero to an unsealed vault with your first secret. You'll need macOS or Linux and a terminal.

1. Install the binaries

   The install script detects your OS and architecture and drops rune and rune-server into /usr/local/bin.

   curl -fsSL https://raw.githubusercontent.com/runelock-io/rune/main/scripts/install.sh | sh
   rune --version

2. Start the server and set a passphrase

   On first run, rune-server creates the vault at ~/.rune/rune.db, asks for a passphrase and prints a root token. The token is shown once and is never stored in plain text — copy it now.

   rune-server

   Set A Passphrase (Required For Sealing and Unsealing):
   
     ────────────────────────────────────────────────────────────────────────
     root token
     ────────────────────────────────────────────────────────────────────────
   
     3f9c0e…(64 hex characters)…a17d
   
     ────────────────────────────────────────────────────────────────────────
     shown once  ·  not stored  ·  full vault access
     ────────────────────────────────────────────────────────────────────────
   
     rune  local-first secrets vault
   
     ➜  api    http://localhost:2710
     ➜  ui     http://localhost:2710/ui/
     ➜  db     /Users/you/.rune/rune.db
   
     ⬡  vault sealed  —  run rune unseal or open the web UI

   Lose the passphrase and the vault can't be unsealed. There is no recovery path — that's the point. Put it in your password manager.

3. Log in and unseal

   Leave the server running and open a second terminal.

   rune login <root-token>
   rune unseal          # prompts for the passphrase, input hidden
   rune status

   ✔ Token saved successfully
   Enter passphrase:
   ✔ Vault Unsealed Successfully
   🔓 Vault is Unsealed

4. Store and read a secret

   rune put db-password 'hunter2-but-longer'
   rune get db-password

   ✔ Secret Stored Successfully
   [SECRET] hunter2-but-longer
   ✔ Secret retrieved

5. Give your app its own token

   Never ship the root token. Create a namespace and a token that can only read it:

   rune namespace create production
   rune put db-password 'hunter2-but-longer' -n production
   rune token create payments-api -n production:read

   Then plug that token into the Java SDK or call the HTTP API directly.

Installation

Rune ships as two binaries: rune (the CLI) and rune-server (the vault, API and Web UI). Both are built for darwin and linux on amd64 and arm64.

Install script

Recommended. Downloads the v1.0.0-RC release for your platform and moves both binaries to /usr/local/bin (uses sudo).

curl -fsSL https://raw.githubusercontent.com/runelock-io/rune/main/scripts/install.sh | sh

curl -fsSL https://raw.githubusercontent.com/runelock-io/rune/main/scripts/install.sh | sh

Detected OS: darwin
Detected ARCH: arm64
Downloading Rune...
Installing Rune...

Rune installed successfully

Run:
  rune --version
  rune-server

Release binaries

Grab them yourself from GitHub Releases. Assets are named rune_<os>_<arch> and rune-server_<os>_<arch>.

VERSION=v1.0.0-RC OS=darwin ARCH=arm64   # OS: darwin|linux  ARCH: amd64|arm64
BASE=https://github.com/runelock-io/rune/releases/download/$VERSION

curl -L $BASE/rune_${OS}_${ARCH} -o rune
curl -L $BASE/rune-server_${OS}_${ARCH} -o rune-server
chmod +x rune rune-server
sudo mv rune rune-server /usr/local/bin/

From source

Requires Go (see go.mod) and Node.js — the Web UI is built with Vite and embedded into rune-server.

git clone https://github.com/runelock-io/rune.git
cd rune
make install        # builds ui/, then bin/rune and bin/rune-server, copies to /usr/local/bin

Homebrew

Verify

rune --version      # rune v1.0.0-RC
rune                # prints the banner and command list

Uninstall

sudo rm /usr/local/bin/rune /usr/local/bin/rune-server
rm -rf ~/.rune      # ⚠ deletes the vault database and your saved CLI token

Architecture

Everything goes through rune-server. The CLI, the Web UI and the Java SDK are all clients of the same HTTP API.

What lives where

Request lifecycle

1. The client sends a request with Authorization: Bearer <token>. Only /status, /unseal, /health and /ui/ are public.
2. The server SHA-256 hashes the token and looks up its record. Unknown or revoked tokens get 401.
3. The handler checks the token's permission for the namespace (read, write, delete, rotate). Failures get 403 [AUTHORIZATION DENIED].
4. The service checks the vault is unsealed, then encrypts or decrypts with the in-memory key.

Seal & unseal

A sealed vault is a locked box: secrets are on disk, encrypted, and the key to read them doesn't exist anywhere. Unsealing derives the key from your passphrase and keeps it in memory until you seal again.

Lifecycle

How unsealing works

1. On first start, rune-server generates a random salt and asks you to set a passphrase.
2. A key is derived from the passphrase and salt, and used to encrypt a known verification value. The passphrase itself is never stored.
3. On unseal, the server derives the key again and tries to decrypt the verification value. If it matches, the key is kept in memory and the vault is unsealed. If not: 401 Invalid Passphrase.
4. seal wipes the key from memory. Restarting the server has the same effect.

What works while sealed

Namespaces

A namespace is a folder for secrets. The same key can exist in several namespaces without conflict — db-password in staging and in production are two different secrets.

The default namespace

default always exists and can't be deleted. Any command without -n uses it.

Working with namespaces

rune namespace create production
rune namespace list
rune put stripe-key 'sk_live_…' -n production
rune namespace delete staging      # asks for confirmation

Rules

• Creating, listing and deleting namespaces requires the root token and an unsealed vault.
• A namespace must exist before you can put secrets in it or grant a token access to it.
• Deleting a namespace deletes every secret in it.

Secrets & versioning

A secret is a key, a value and a namespace. Every value is encrypted individually with AES-256-GCM and a fresh random nonce, and every rotation is kept as a new, separately encrypted version.

Versions

• rune put writes the secret as version 1.
• rune rotate creates the next version (2, 3, …). Earlier versions stay readable with rune get --version N.
• rune history lists every version with its created and rotated timestamps.

Deleting

rune delete removes the secret and every version of it. Nothing lingers, including copies held for system tokens.

Keys

Keys are trimmed, a leading / is dropped, and a leading default/ is dropped. Use the -n flag for namespaces rather than putting them in the key.

Rotation

Rotating a secret replaces its value with a freshly generated one and bumps the version. The old value stays in history, encrypted.

Manual rotation

rune rotate db-password -n production

  SECRET ROTATED
  ─────────────────────────────────────────────
  Namespace:   production
  Key:         db-password
  New Value:   Vq3m9X0rK1…
  ─────────────────────────────────────────────

✔ Secret rotated successfully

The new value is 32 cryptographically random bytes, base64url-encoded (43 characters). Rotating requires the rotate permission on the namespace.

Automated rotation

Rune can rotate secrets for you on a schedule, so long-lived credentials don't stay long-lived. Every automated rotation is a normal rotation: a new version, the old one kept, and an entry in the audit log.

Tokens & RBAC

Every request to Rune carries a token. A token says who is asking and what they may do, namespace by namespace.

Kinds of token

Permissions

Granting access

Pass -n namespace:perm,perm once per namespace. A namespace with no permissions listed gets all four.

# CI can deploy to production, nothing else
rune token create ci-deploy -n production:read,write

# read production, read+write staging
rune token create dev-laptop -n production:read -n staging:read,write

# everything in sandbox
rune token create playground -n sandbox

What denial looks like

✖ [AUTHORIZATION DENIED]: Token cannot write to this namespace

Over HTTP that's a 403. Unknown tokens get 401 invalid token; revoked ones 401 token has been revoked.

How tokens are stored

A token is 32 random bytes, hex-encoded (64 characters). Rune stores only its SHA-256 hash, so the plain token is shown exactly once — when it's created.

Revoking

rune token list                 # find the ID
rune token revoke tkn_1730451234567890

Revocation is immediate. Revoking a system token also deletes the encrypted copies it used to read while sealed.

Service identities

Applications shouldn't borrow a human's token. A system token is an identity for one service: read-only, bound to one namespace, and able to read secrets even while the vault is sealed — so a restart of rune-server doesn't take your apps down with it.

How it works

1. While unsealed, root creates a system token for a namespace.
2. Rune derives a separate key from the plain token and re-encrypts that namespace's secrets with it. That key is itself stored encrypted under the vault key.
3. When the vault is sealed, a request with the system token re-derives its key from the token and reads its own copy. Without the token, the copy can't be decrypted.
4. Puts, rotations and deletes in the namespace keep the copies in sync. Revoking the token deletes them.

Create one

System tokens are created through the HTTP API with the root token:

curl -X POST http://localhost:2710/token/create-system \
  -H "Authorization: Bearer $RUNE_ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"payments-api","namespace":"production"}'

{
  "token": "9a41…e07c",
  "record": {
    "id": "stk_1730451234567890",
    "name": "payments-api",
    "namespace": "production",
    "namespaces": [{ "namespace": "production", "permissions": ["read"] }],
    "read_only": true,
    "system": true
  }
}

Token expiration

Tokens can be given a lifetime. When it runs out, the token stops working — no clean-up ticket, no forgotten CI variable that still opens production two years later.

Why it matters

• Short-lived tokens for CI jobs and one-off scripts limit the blast radius of a leak.
• Long-lived service tokens can still be revoked at any time with rune token revoke.

Audit logging

Every meaningful action in the vault leaves a record: which token, which operation, which secret, when, and whether it was allowed.

What gets recorded

Denied requests are logged too — a token repeatedly bouncing off [AUTHORIZATION DENIED] is exactly what you want to notice.

Security model

Rune is designed so that a copy of rune.db on its own is useless, and a leaked token is only as powerful as you made it.

Cryptography

Protected against

• Someone copying ~/.rune/rune.db — they get ciphertext and hashes.
• A leaked app token reaching beyond its namespaces and permissions.
• Old values disappearing on rotation — they're versioned, not overwritten.

Your job

• The passphrase — there's no recovery. Store it somewhere safe.
• The root token — use it to administer, not to run apps.
• ~/.rune/config.json holds the CLI's token in plain text. Keep it readable only by you: chmod 600 ~/.rune/config.json.
• Transport — rune-server speaks plain HTTP on :2710. Keep it on localhost or a private network, or put TLS in front of it.
• Shell history — rune put key value lands in your history. Quote values, and consider a leading space with HISTCONTROL=ignorespace.

CLI overview

rune is a thin client for rune-server. It reads its token from ~/.rune/config.json and talks to http://localhost:2710.

rune                 # banner + command list
rune --version       # or -v
rune <command> --help

Commands

Namespaces

Secret commands take -n / --namespace. Leave it out and you get default.

Output conventions

✔ success
✖ error — usually the server's message, e.g. [OPERATION DENIED]: Vault is Sealed
➜ info
! warning

Colours are disabled when NO_COLOR is set or output isn't a terminal.

rune login

Saves a token to ~/.rune/config.json. Every other authenticated command uses it.

rune login <token>

✔ Token saved successfully

Switch identities by logging in again with another token. Without a saved token, commands fail with:

✖ [AUTHENTICATION FAILED] Please login first using: rune login <token>

status · unseal · seal

Three commands for the vault's state. See Seal & unseal for the why.

rune status

rune status

🔒 Vault is Sealed

No token needed.

rune unseal

Prompts for the passphrase with input hidden. No token needed.

Enter passphrase:
✔ Vault Unsealed Successfully

A wrong passphrase returns ✖ error: Invalid Passphrase.

rune seal

Clears the key from the server's memory. Requires a valid token.

✔ Vault Sealed Successfully

rune put

Encrypts a value and stores it under a key.

rune put <key> <value> [-n namespace]

Flags

Examples

rune put db-password 'hunter2-but-longer'
rune put stripe-key 'sk_live_51Hx…' -n production

✔ Secret Stored Successfully

Requires write on the namespace.

rune get

Decrypts and prints a secret. The vault must be unsealed.

rune get <key> [-n namespace] [--version N]

Flags

Examples

rune get db-password -n production
rune get db-password -n production --version 2

[SECRET] hunter2-but-longer
✔ Secret retrieved

Requires read on the namespace.

rune list

Lists keys — never values.

rune list [-n namespace]

Stored Secrets:

  [SECRET] db-password
  [SECRET] redis-url

An empty namespace prints ➜ No stored keys found. Requires read.

rune delete

Deletes a secret and every version of it, after asking.

rune delete <key> [-n namespace]

Are you sure you want to delete secret 'redis-url' (namespace: production)? (y/N): y
✔ Secret deleted

Anything but y prints ➜ Operation Cancelled. Requires delete.

rune rotate

Replaces the value with 32 random bytes (base64url) and creates the next version.

rune rotate <key> [-n namespace]

  SECRET ROTATED
  ─────────────────────────────────────────────
  Namespace:   production
  Key:         db-password
  New Value:   Vq3m9X0rK1…
  ─────────────────────────────────────────────

✔ Secret rotated successfully

Requires rotate. The secret must already exist.

rune history

Shows every version of a secret with when it was created and rotated.

rune history <key> [-n namespace]

  SECRET HISTORY
  ─────────────────────────────────────────────────────────
  VERSION    CREATED                   ROTATED
  ─────────────────────────────────────────────────────────
  1          2026-10-02T09:12:04+05:30 -
  2          2026-10-02T09:12:04+05:30 2026-10-09T14:03:51+05:30
  3          2026-10-02T09:12:04+05:30 2026-11-01T10:30:42+05:30
  ─────────────────────────────────────────────────────────

Fetch any of them with rune get <key> --version N. Requires read.

rune namespace

Manage namespaces. All subcommands need the root token and an unsealed vault.

create

rune namespace create production

✔ [NAMESPACE CREATED] Created namespace

list

Namespaces:

[NAMESPACES] default
[NAMESPACES] production

delete

Are you sure you want to delete namespace 'staging'? (y/N): y
✔ Namespace deleted

rune token

Manage access tokens. All subcommands need the root token.

create

rune token create [name] -n <namespace[:perms]> [-n …]

rune token create ci-deploy -n production:read,write -n staging:read

✔ Token created successfully

  ID:          tkn_1730451234567890
  Name:        ci-deploy
  Created At:  2026-11-01T10:30:42+05:30

  production           read, write
  staging              read

  Token: 5b0e…(64 hex characters)…c91f

list

Tokens:

  ID                           NAME                 CREATED AT                TYPE       STATUS
  -------------------------------------------------------------------------------------------------
  root                         root                 2026-10-01T09:00:00+05:30 regular    active
  tkn_1730451234567890         ci-deploy            2026-11-01T10:30:42+05:30 regular    active
  stk_1730451299999999         payments-api         2026-11-01T10:31:47+05:30 system     active

revoke

rune token revoke tkn_1730451234567890

✔ Token revoked

rune-server

The vault. One process that stores encrypted secrets, enforces tokens, serves the HTTP API and hosts the Web UI.

Start it

rune-server

  rune  local-first secrets vault

  ➜  api    http://localhost:2710
  ➜  ui     http://localhost:2710/ui/
  ➜  db     /Users/you/.rune/rune.db

  ⬡  vault sealed  —  run rune unseal or open the web UI

On the very first start it also asks you to set a passphrase and prints the root token once — see the Quickstart.

Defaults

Running it as a service

Because the vault starts sealed, a restart means someone runs rune unseal again. Apps using system tokens keep reading in the meantime. A minimal systemd unit:

[Unit]
Description=Rune secrets vault
After=network.target

[Service]
ExecStart=/usr/local/bin/rune-server
User=rune
Restart=on-failure

[Install]
WantedBy=multi-user.target

Routes

Web UI

A browser interface to the same vault, built into rune-server. No separate install, no desktop app — open http://localhost:2710/ui/.

What you can do

• Unseal the vault from the browser.
• Dashboard — totals for secrets, namespaces, rotated secrets and tokens, secrets per namespace, tokens created per month.
• Secrets — browse by namespace, reveal, create, rotate, delete, inspect versions.
• Namespaces and tokens — create, scope with permissions, revoke.

Permissions

The UI goes through the same HTTP API and the same token rules as everything else: a scoped token can only see and change what it's allowed to. Dashboard stats, namespaces and token management need root.

Under the hood

React + Vite + Tailwind, compiled and embedded into the rune-server binary with Go's embed. Building from source? make server-build runs npm install && npm run build in ui/ first.

HTTP API

The CLI, Web UI and SDK are all built on this API. Anything that speaks HTTP can use Rune.

Base URL

http://localhost:2710

Authentication

Send a token as a bearer header on every request except /health, /status and /unseal.

curl -H "Authorization: Bearer $RUNE_TOKEN" \
  "http://localhost:2710/secret/get?namespace=production&key=db-password"

Errors

Errors come back as a plain-text body with an HTTP status.

Endpoints

Vault endpoints

Health

Returns ok. Use it for liveness checks.

Status

Returns sealed or unsealed as plain text.

Unseal

curl -X POST http://localhost:2710/unseal \
  -H "Content-Type: application/json" \
  -d '{"passphrase":"…"}'

200 unsealed · 401 Invalid Passphrase · 500 Vault Not Initialized

Seal

Clears the key from memory. Returns sealed.

Secrets endpoints

namespace defaults to default everywhere it's optional.

Put a secret

curl -X POST http://localhost:2710/secret/put \
  -H "Authorization: Bearer $RUNE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"db-password","value":"hunter2","namespace":"production"}'

HttpRequest req = HttpRequest.newBuilder(URI.create("http://localhost:2710/secret/put"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"key\":\"db-password\",\"value\":\"hunter2\",\"namespace\":\"production\"}"))
    .build();
HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());

body := strings.NewReader(`{"key":"db-password","value":"hunter2","namespace":"production"}`)
req, _ := http.NewRequest("POST", "http://localhost:2710/secret/put", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

Returns 201 Created.

Get a secret

{ "value": "hunter2" }

Works while sealed for system tokens.

List keys

["db-password", "redis-url"]

Get all secrets in a namespace

{ "db-password": "hunter2", "redis-url": "redis://cache.internal:6379/0" }

Rotate

{ "value": "Vq3m9X0rK1…" }

History

[
  { "version": 1, "created_at": "2026-10-02T09:12:04+05:30", "updated_at": "2026-10-02T09:12:04+05:30", "rotated_at": "" },
  { "version": 2, "created_at": "2026-10-02T09:12:04+05:30", "updated_at": "2026-10-09T14:03:51+05:30", "rotated_at": "2026-10-09T14:03:51+05:30" }
]

A specific version

{ "value": "hunter2" }

Delete

{ "key": "redis-url", "namespace": "production" }

Removes the secret and all versions. Returns 200.

Tokens endpoints

Who am I?

{
  "id": "tkn_1730451234567890",
  "name": "ci-deploy",
  "created_at": "2026-11-01T10:30:42+05:30",
  "revoked": false,
  "namespaces": [{ "namespace": "production", "permissions": ["read", "write"] }]
}

Create a token

{ "token": "5b0e…c91f", "record": { "id": "tkn_…", "name": "ci-deploy", "namespaces": [ … ] } }

Create a system token

{ "name": "payments-api", "namespace": "production" }

Read-only, single namespace, reads while sealed. See Service identities.

List tokens

Revoke

{ "id": "tkn_1730451234567890" }

Namespaces & stats

All of these need the root token and an unsealed vault.

Create

{ "name": "production" }

List

["default", "production", "staging"]

Delete

{ "name": "staging" }

Deletes the namespace and every secret in it. default is refused.

Stats

{
  "total_secrets": 24,
  "total_namespaces": 4,
  "rotated_secrets": 9,
  "total_tokens": 8,
  "active_tokens": 6,
  "revoked_tokens": 2,
  "secrets_by_namespace": [{ "namespace": "production", "count": 11 }],
  "tokens_by_month": [{ "month": "2026-11", "count": 3 }]
}

Spring Boot starter

rune-spring-boot-starter fetches every secret in a namespace at startup and exposes them as Spring properties — before any of your beans are created.

Install

<dependency>
  <groupId>io.rune</groupId>
  <artifactId>rune-spring-boot-starter</artifactId>
  <version>0.1.0</version>
</dependency>

dependencies {
    implementation 'io.rune:rune-spring-boot-starter:0.1.0'
}

Java 17+, Spring Boot 3. No extra HTTP or JSON libraries — it uses java.net.http.

Configure

rune:
  url: http://localhost:2710
  token: ${RUNE_TOKEN}
  namespace: production
  fail-fast: true

Use secrets as properties

Each secret becomes rune.<key>, added as the highest-precedence property source:

@Configuration
class DataSourceConfig {

    @Value("${rune.db-password}")
    private String dbPassword;

}

spring:
  datasource:
    password: ${rune.db-password}

Use RuneClient

When both rune.url and rune.token are set, a RuneClient bean is available for runtime lookups:

@Service
class PaymentsService {

    private final RuneClient rune;

    PaymentsService(RuneClient rune) {
        this.rune = rune;
    }

    String stripeKey() {
        return rune.getSecret("production", "stripe-key");
    }

    List<String> keys() {
        return rune.listKeys("production");
    }
}

Non-200 responses and connection failures throw RuneException.

How it works

1. Spring loads application.yml

   Including rune.*.

2. RuneEnvironmentPostProcessor runs

   Before any bean is created, it lists and fetches the namespace's secrets.

3. A rune property source is added first

   So ${rune.<key>} wins over everything else.

4. Your beans start

   With secrets in hand — nothing on disk, nothing in git.

Kubernetes next release

The next release brings Rune to your cluster. Two pieces are in the works.

Until then: run rune-server somewhere your pods can reach, give each service a system token, and read secrets at startup with the Java SDK or the HTTP API.

Troubleshooting

The messages you're most likely to meet, and what they mean.

Roadmap

Follow along on GitHub. Rune is licensed under Apache 2.0.