Phase 1 — Install and configure

Required: @restormel/keys. Phase 5 UI (keys-svelte, keys-react, keys-elements) — add when on npm. Verify with npm view @restormel/keys-svelte version before relying on install.

Headless / SvelteKit Phases 1–4:

pnpm add @restormel/keys

Next.js + UI (Phase 5, only if npm view confirms packages):

pnpm add @restormel/keys @restormel/keys-react @restormel/keys-elements

SvelteKit + UI (Phase 5, only if npm view confirms packages):

pnpm add @restormel/keys @restormel/keys-svelte

You'll see

The packages appear in your package.json dependencies. No build errors.

How to test

# Confirm the package installed correctly
node -e "const k = require('@restormel/keys'); console.log('OK:', Object.keys(k).length, 'exports')"

If you use ESM ("type": "module" in your package.json):

node --input-type=module -e "import { createKeys } from '@restormel/keys'; console.log('OK: createKeys is', typeof createKeys)"

Option A — npx @restormel/keys-cli init when the package resolves on npm. If 404, use Option B.

Option B — Create restormel.config.json in the app root:

{
  "framework": "sveltekit",
  "providers": []
}

Use framework: next | sveltekit | react | astro | none.

How to test

npx @restormel/doctor

Doctor requires @restormel/keys + config. Optional UI warnings are OK for headless setups.

Open the Dashboard and sign in with GitHub.

1. Create a workspace (if you don't have one). This is your top-level organisational container. Name it after your company or team.
2. Create a project. Name it after your app (e.g. "My Writing Tool"). The project is where routes, policies, and keys live.
3. Create an environment within the project: production. You can add staging later. The environment scopes routes and policies to a deployment context.

You'll see

The project detail page in the dashboard with: project name and ID; an "Environments" section showing production; empty "Routes" and "Policies" sections (you'll fill these in Phases 3–4); an "API Keys" section (you'll generate a Gateway Key next).

How to test

The project detail page loads without errors. The environment production is listed.

Still in the Dashboard, on your project detail page:

1. Click Generate API key (or navigate to the API Keys section).
2. Copy the full key immediately. It has the format rk_… and is shown only once.
3. Store it securely. This is your Gateway Key — the credential your backend uses to authenticate to the Restormel resolve API.

You'll see

A key displayed once with a "Copy" button. After you navigate away, you see only the key prefix (e.g. rk_a3f…) in the dashboard — the full key is not retrievable.

How to test

You test the key works in Phase 2 when you make your first resolve call. For now, confirm it's stored:

# Add to your .env (gitignored) — NOT .env.example
# RESTORMEL_GATEWAY_KEY=rk_your_key_here
# RESTORMEL_PROJECT_ID=your_project_id_here
# RESTORMEL_ENVIRONMENT_ID=production

Update .env.example with placeholder names (no values):

# .env.example
RESTORMEL_GATEWAY_KEY=
RESTORMEL_PROJECT_ID=
RESTORMEL_ENVIRONMENT_ID=

This step is about choosing how your stack reaches providers. Restormel is designed to work with external gateways (OpenRouter, Vercel AI Gateway, Portkey) and with builder-managed direct provider keys (env vars / secret manager). Restormel does not need to custody raw provider secrets by default.

Option A — Gateway-backed provider access (recommended)

Keep your gateway as the provider access layer, and use Restormel for routing, policies, health, analytics, and progressive rollout. See: OpenRouter, Vercel AI Gateway, Portkey.

Option B — Builder-managed direct providers

Keep provider keys in your own environment (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY) or secret manager. Restormel resolve tells you which provider/model to call; your app supplies provider access from its own infrastructure.

You'll see

You have a clear provider access mode for your stack (gateway-backed or builder-managed direct). If you are using a gateway, your app still uses the gateway’s auth and endpoint; Restormel adds the control layer.

How to test

No code-level test in this phase. You’ll verify your chosen mode in Phase 2 when you make your first resolve call.

Now that you have a config (and optionally env vars), run the doctor check again:

npx @restormel/doctor

You'll see

Restormel Doctor checks framework detection, package versions, and config validity. Example output:

✔ Framework detection — SvelteKit
✔ Core package (@restormel/keys) — installed
○ UI packages (Phase 5 — optional) — not installed: @restormel/keys-svelte — OK for headless
✔ restormel.config.json — found

OK

Cloud env vars (RESTORMEL_GATEWAY_KEY, RESTORMEL_PROJECT_ID, RESTORMEL_ENVIRONMENT_ID) are not validated by the CLI. You confirm they work in Phase 2 when you call the resolve endpoint.

How to test

npx @restormel/doctor && echo "PASS" || echo "FAIL"

Make sure your repo's .env.example documents the new variables so collaborators know what to set:

# .env.example — Restormel Keys integration
RESTORMEL_GATEWAY_KEY=
RESTORMEL_PROJECT_ID=
RESTORMEL_ENVIRONMENT_ID=
# Optional: feature flag for phased rollout (see Phase 0)
USE_RESTORMEL_KEYS=false