Symbol Docs
Features

End-to-End Encryption

Encrypt capsule content so only you (and your devices) can read it.

Symbol supports end-to-end encryption (E2EE) for capsule content. When enabled, your capsules are encrypted on-device before being sent to the server. The server never sees plaintext.

How It Works

  1. You enable encryption in the Symbol app and set a passphrase.
  2. A random master key is generated and stored encrypted (wrapped) on the server using a key derived from your passphrase.
  3. Each capsule gets its own content encryption key (CEK), wrapped by your master key.
  4. Only devices that have your master key can decrypt capsule content.

The web UI at symbol.chat cannot decrypt encrypted capsules. You read and write encrypted content through the Symbol app or the Desktop MCP.

Linking the Desktop MCP

The Desktop MCP needs your master key to decrypt capsules. Since the key never leaves your devices in plaintext, you transfer it using a device-link flow:

  1. The MCP generates a one-time token and shows it to you (or the AI relays it).
  2. You enter the token in the Symbol app: Settings, then Encryption, then Link Desktop.
  3. The app securely transfers your master key to the MCP over an encrypted channel.
  4. The MCP can now decrypt your capsules for the rest of the session.

If the MCP restarts (or the extension reloads), you will need to link again unless the key is cached in your OS keychain.

Recovery Key

You can generate a recovery key under Settings, then Encryption, then Recovery Key in the Symbol app. This is a long base58 string that can unlock your master key without the device-link flow.

To use it with the Desktop MCP, set encryption.recoveryKey in ~/.symbol/config.json or the SYMBOL_ENCRYPTION_RECOVERY_KEY environment variable. The MCP will derive your master key automatically on startup, with no device linking required.

Store your recovery key securely. If you lose both your passphrase and your recovery key, encrypted capsules cannot be recovered.

Troubleshooting

"Decryption failed: key mismatch"

This error means the capsule was encrypted with a different master key than the one currently loaded. This typically happens after an encryption reset, where you disabled encryption and re-enabled it with a new passphrase, creating a new master key. Capsules encrypted with the previous key remain in the database but cannot be decrypted with the new key.

How to verify:

  1. Open the same capsule in the Symbol app.
  2. If the app also shows a decryption error (or blank/garbled content), the capsule was encrypted with an old key and cannot be recovered.
  3. If the app decrypts it fine, the issue is with the MCP's key. Try clearing keys (encryption_status with action="clear_keys") and re-linking.

How to confirm your encryption is working:

  1. Create a new encrypted capsule in the Symbol app (or via MCP with encryption enabled).
  2. Read it back using get_encrypted_capsule. If the content decrypts, your setup is correct.
  3. Old capsules that fail are orphaned from a previous master key.

"Encryption keys are not loaded"

The MCP does not have your master key yet. Follow the device-link flow:

  1. Call encryption_status with action="authenticate" to get a token.
  2. Enter the token in the Symbol app: Settings, then Encryption, then Link Desktop.
  3. Call encryption_status with action="complete_link".

If you have a recovery key configured, the MCP loads the master key automatically and you should not see this error. Check that encryption.recoveryKey is set correctly in your config.

The token is valid for a limited time. If you waited too long, call encryption_status with action="authenticate" again to generate a new token.

Capsule works in app but not in MCP

If a capsule decrypts in the Symbol app but fails in the MCP:

  1. Clear MCP keys: call encryption_status with action="clear_keys".
  2. Re-link: call encryption_status with action="authenticate", enter the token in the app, then call action="complete_link".
  3. Retry reading the capsule.

This can happen if the MCP cached a stale key from a previous session.

After an encryption reset

When you reset encryption (disable then re-enable with a new passphrase), all capsules encrypted with the old key become permanently unreadable. There is no way to recover them without the original passphrase or recovery key.

Before resetting encryption:

  • Export or back up any capsules you need.
  • Delete capsules you no longer need.
  • Understand that this is irreversible for old encrypted content.

Attachments

Attach files, screenshots, and logs to any capsule.

Archiving

How archiving works as a soft-delete safety net for capsules, with automatic cleanup after 90 days.

On this page

How It WorksLinking the Desktop MCPRecovery KeyTroubleshooting"Decryption failed: key mismatch""Encryption keys are not loaded""Device-link session expired"Capsule works in app but not in MCPAfter an encryption reset