Secrets

Some skills need a token of their own, such as a changelog hub's ingest token or a GitHub token. Save it once as a secret and your bots can use it without ever seeing it: a bot names the secret, and Brainwrite puts the real value into the request only when it sends it, and only to the one site you allow.

Secrets work in the Brainwrite desktop app, for the bots on that computer. They are not yet available on Brainwrite Cloud, on a server you run yourself, or from the phone apps.

When a bot asks for one

When a task needs a token you have not saved, the bot asks for it in the chat with a secure card:

1. The card says Secret needed with the secret's name, and why the bot needs it.
2. Check Sent only to. The bot suggests the site; make sure it is your real site before saving.
3. Paste the token and choose Save securely. The bot continues the task on its own.

Choose Not now to decline; the bot carries on without it if it can. The token never appears in the chat, and only the bot that asked may use it until you change that in Settings.

A bot should never ask you to paste a token into the chat. If you paste one anyway, the bot will not use it: it tells you to rotate the token, since it is now part of the conversation, and asks for the new one with the secure card.

On a phone or another computer connected to this one, the card asks you to finish on the computer that runs your bots.

Manage your secrets

Open Settings, then Secrets (under AI). The list shows each secret's name, the site it is sent to, which bots may use it, and when it was last used.

Choose Add secret to save one yourself:

• Name: capital letters, digits and underscores, the way the skill names it (for example CHANGELOG_INGEST_TOKEN).
• Value: stored in your computer's secure store. It is never shown again; you can only replace it.
• Sent only to: one https site, such as https://api.example.com. A request to any other site is refused.
• How it is sent: Authorization: Bearer (the usual choice), a header you name (such as X-API-Key), or only where the bot writes {{secret:NAME}} in the request.
• Bots that may use it: all bots, or only the bots you choose.

Use the pencil to change a secret's site, how it is sent or its bots; leave Value empty to keep the saved value. Use the bin to delete it.

Uploading files

Bots can also upload files with a secret, for example a changelog entry's text and its cover image, the way a skill's curl -F command does. A bot may upload any file your computer account can open, on a Mac or on Windows: files in Brainwrite's own folders, your Desktop, Documents, Downloads, or any other folder. One request holds at most 10 MB, up to 50 files.

On a Mac, if Brainwrite has not been allowed to open a folder such as Desktop or Documents, the bot tells you so. Allow Brainwrite in System Settings → Privacy & Security → Files and Folders, then ask the bot to try again.

Files are sent exactly as they are, to the secret's one site only.

How your token stays safe

• The value is kept in your computer's secure store and is never added to the chat, a bot's instructions, its shell or its logs.
• Brainwrite makes the request itself, over https, to the secret's one site. It never follows a redirect to another address.
• Anything the site sends back is cleaned of the token before the bot sees it.
• Each use is recorded with the secret's name, the site and the time, never the value.