Skip to main content

Security

How Toby keeps your API keys and integration secrets on your Mac, and how backup and restore work.

What Toby protects​

Toby stores secrets on your computer. There is no Toby-hosted cloud for credentials. Optional settings sync stores only an encrypted snapshot in your iCloud Drive or a folder you already sync.

GoalHow Toby handles it
Keep secrets out of plain text filesOn macOS, credentials.json is encrypted at rest
Let you move settings between MacsPassword-protected backup files (.tbybak) and optional settings sync
Avoid leaking keys in the UISettings shows masked values (••••••) for secrets

Toby does not replace full-disk encryption, a strong Mac login password, or caution about malware running as your user. Treat your Mac login and Keychain as part of your security boundary.

Where data lives​

LocationWhat it holds
~/.toby/config.jsonPreferences that are not secrets (personas, which integrations are connected, defaults, web search, …)
~/.toby/credentials.jsonSecrets: AI keys, Email/Notion/Slack tokens, MCP tokens/env, and other connection credentials
Other ~/.toby/… pathsChat history, memories, recordings, library files, skills — see Configuration overview

Integration passwords and API keys live in credentials. “Connected” status alone lives in config — so a backup only helps for secrets that were actually saved when you created it.

Credentials encryption (macOS)​

On Mac, Toby encrypts the credentials file with AES-256-GCM. The encryption key is stored in the macOS Keychain, not next to the file.

Keychain fieldValue
Servicedev.toby.credentials
Accountdata-encryption-key

You may see a one-time prompt the first time Toby needs to use this Keychain item. After that, Settings and plugins keep working as usual — encryption is transparent while you use Toby.

What this means in practice​

  • Opening credentials.json in a text editor shows ciphertext, not raw API keys.
  • Copying only credentials.json to another computer does not unlock your secrets (the Keychain item does not travel with the file).
  • If the Keychain item is deleted and you have no backup, Toby cannot decrypt the file — re-enter secrets in Settings, restore a .tbybak backup, or join settings sync from another Mac.

Settings sync​

Settings → Sync can keep an encrypted copy of settings and secrets in iCloud Drive or a folder you already replicate so your other Macs stay in sync. The wrapping password is stored in this Mac’s Keychain (dev.toby.sync), not in the remote file. See Settings sync for setup, what is included, and password recovery.

Backup and restore​

Use a password-protected backup when you want a portable copy of settings, secrets, and your Toby data (new Mac, reinstall, safety before a big change).

From Toby.app​

MenuAction
File → Backup Toby Data…Choose a password, then a save location for a .tbybak file
File → Restore Toby Data…Pick a .tbybak file, enter the password if asked, confirm replace

From Terminal​

toby config backup
toby config backup ~/Desktop
toby config restore ~/Desktop/toby-config-backup-….tbybak

The app menus use the same .tbybak format as these CLI commands.

What a backup includes​

IncludedNot included
Settings in config.json (personas, connection flags, defaults, …)Installed plugin packages and local plugin data
Secrets in credentials (AI keys, Email, Notion, Slack, and other plugin credentials, transcription keys)Skills and persona image files
Chat database (chats, projects, schedules, flows, and run history)App appearance and other Mac-only preferences
Memories databaseSymbolic links inside project folders
Project folders, including projects stored outside Toby's data folder
Recordings — audio, transcripts, and summaries
Library files — copied documents, PDFs, images, and extracted textLive two-way merge of library files across Macs

Backups can be large because they include audio. The archive is encrypted with your backup password (separate from the Keychain). Anyone with the file and that password can restore your secrets — choose a strong password and store the file carefully.

Restore notes​

  • Restore replaces current settings, credentials, chat data, memories, project files, recordings, and library items on this Mac.
  • Projects are restored inside Toby's data folder. A project that used a custom folder keeps a copy of its files there; the original folder is left untouched.
  • After restore, Toby re-encrypts credentials for this Mac’s Keychain.
  • Toby restarts its daemon before applying database, project, recording, and library data. You cannot restore while a recording is in progress.
  • Prefer restore over manually copying credentials.json.

Tips​

  1. Back up before major upgrades or when changing machines.
  2. Never commit credentials.json or .tbybak files to git.
  3. If an integration looks “connected” but tools fail, open Settings and re-enter that integration’s secrets — connection flags and secrets are stored separately.
  4. Full-disk encryption (FileVault) plus a locked Mac login still matter.