Docs menu

Keys

Keys are the settings and secrets your app reads from its environment: an API key, a session secret, a public URL. Secretbase keeps them encrypted on the computer and gives them to the app when it starts.

Set a key

In the app's folder:

$ secretbase keys set API_KEY

It asks for the value, which isn't shown while you type and never goes on the command line. Then it says "Saved API_KEY (private) for my-app. A running app restarts to use it." Your app reads it as the environment variable API_KEY.

From another folder add --app my-app; from a laptop, --app my-app --to home. On the dashboard: the app's Settings, Keys. A value can't be read back after it is saved.

See and remove keys

$ secretbase keys list
my-app has no keys. Add one with: secretbase keys set <NAME>
$ secretbase keys remove API_KEY

keys list shows each key's name and whether it is private or public, never its value. keys remove says "Removed API_KEY from my-app." (a name the app has no key of: "my-app has no key API_KEY.").

Private and public

A key is private unless you add --public. A private value is hidden in the app's logs (as [hidden: API_KEY]), and a publish stops if it appears in the website's code: "API_KEY is private but appears in website code". Use --public only for a value that may be seen in your website's code.

A public key is also there when Secretbase builds the app, as on Vercel: a Vite or Next.js build bakes VITE_… or NEXT_PUBLIC_… values in, and a Dockerfile gets them as build args (declare them with ARG NAME). Publish again after changing one, so the build picks it up. Private keys never reach a build.

Keys an app needs before it goes public

An app can list the keys it can't run without in its secretbase.json:

{"required_keys": ["API_KEY", "SESSION_SECRET"]}

A first publish then waits, offline, until each is set: "Waiting for keys before my-app goes public: API_KEY, SESSION_SECRET. Set each with …". It goes public by itself once all are set. When an earlier release is online, it keeps serving meanwhile.

If something goes wrong

  • "The value is empty. Nothing was saved.": type or paste the value when it asks.
  • "API_KEY is too short to hide in logs.": a private value needs 8 characters or more.
  • "PORT is set by Secretbase itself; pick another name.": PORT, HOST, DATA_DIR, HOME and PATH are taken.
  • A key's name uses letters, digits and _, and doesn't start with a digit.