Visual Environment Variable (.env) Vault

The Pocket Kit Environment Vault provides encrypted configuration management for each of your PocketBase instances.

Why Use the Env Vault?

When writing PocketBase JavaScript server hooks (pb_hooks), you often need to communicate with external APIs (Stripe, OpenAI, Resend, AWS S3, Algolia). Hardcoding API keys into your source code or database migrations creates security risks.

The Environment Vault provides:

• AES-256-GCM Encryption at Rest: Keys are encrypted in the Control Plane database.
• Isolated Per-Tenant .env Files: Written with strict 0600 Linux permissions inside /home/admin/pocket-kit/tenants/<instance_id>/.env.
• Automatic Runtime Process Injection: The Node.js Runner Daemon injects all variables directly into the child PocketBase process environment when starting or restarting an instance.
• Visual Key-Value & Raw .env Import: A visual UI with secret masking and instant raw .env copy/paste parsing.

---

Accessing Environment Variables in Server Hooks

Any variable saved in the vault is accessible inside your instance’s pb_hooks/*.pb.js scripts via $os.getenv():

/// <reference path="../pb_data/types.d.ts" />

routerAdd("POST", "/api/v1/checkout", (e) => {
  // Read encrypted secret key injected from Pocket Kit Env Vault
  const stripeSecret = $os.getenv("STRIPE_SECRET_KEY");
  const webhookSecret = $os.getenv("STRIPE_WEBHOOK_SECRET");

  if (!stripeSecret) {
    return e.json(500, { error: "Stripe configuration missing" });
  }

  // Communicate with Stripe API...
  const res = $http.send({
    url: "https://api.stripe.com/v1/checkout/sessions",
    method: "POST",
    headers: {
      "Authorization": "Bearer " + stripeSecret,
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: "success_url=https://example.com/success&mode=payment"
  });

  return e.json(200, res.json);
});

---

Managing Variables from the Dashboard

1. Navigate to Instances in your Pocket Kit console.
2. On any instance card, click Env Vault (or click the context menu and select “Environment Vault”).
3. Add key-value pairs (e.g. OPENAI_API_KEY, RESEND_API_KEY).
4. Toggle the “Secret (Masked)” switch for sensitive tokens.
5. Click “Save Changes”.
6. Pocket Kit will encrypt the variables, write the isolated .env file, and reload your instance process.