Pubky Ring

Your keychain for the Pubky ecosystem. Manage your pubkys, authorize services, and stay in control—no accounts, no passwords.

Pubky Ring is the key manager for your identity in the Pubky ecosystem. It lets you securely manage your pubkys—the public keys that power your presence across decentralized apps.

What You Can Do

• Authorize or revoke access to services
• Organize and sync your pubkys across devices
• View and control active sessions
• Stay fully self-custodial, with no accounts or tracking

Accepted Input Formats

Pubky Ring accepts input via deeplinks, QR code scanning, and clipboard pasting. All parsing is handled by src/utils/inputParser.ts.

Deeplinks

Registered URL schemes: pubkyring:// and pubkyauth://

Action	Format	Parameters
Auth	pubkyauth:///?relay={url}&secret={secret}&caps={caps}	relay: relay URL, secret: secret key, caps: comma-separated capabilities
Sign In	pubkyring://signin?caps=...&secret=...&relay=...	Same as Auth (converted internally)
Signup	pubkyring://signup?hs={homeserver}&st={signup_token}&relay=...&secret=...&caps=...	hs: homeserver URL, st: invite/signup token
Session	pubkyring://session?callback={callback_url}	callback: URL-encoded callback URL
Migrate	pubkyring://migrate?index={n}&total={total}&key={key}	index: 0-based frame index, total: frame count, key: mnemonic or secret key

Clipboard (Pasting)

Format	Example	Action
Recovery Phrase	word1 word2 word3 ... word12 (12 BIP39 words)	Import
Encrypted Secret Key	Encrypted key string	Import
Invite Code	XXXX-XXXX-XXXX	Invite
Invite URL	https://example.com/invite/XXXX-XXXX-XXXX	Invite (code extracted)
Any deeplink	pubkyring://signup?...	Same as deeplink

Note: Pasted input is normalized—hyphens, underscores, and plus signs are converted to spaces for recovery phrases.

QR Code Scanning

Accepts all deeplink and clipboard formats when encoded in a QR code. Additionally supports:

Format	Description
Animated QR	Multi-frame QR codes cycling through migrate deeplinks for bulk key import

Input Priority Order

When parsing input, the first matching format wins:

1. Migrate deeplinks
2. Signup deeplinks
3. Session deeplinks
4. Sign-in deeplinks
5. Auth URLs (pubkyauth:///)
6. Invite codes in URLs
7. Standalone invite codes
8. Recovery phrases (12 words)
9. Encrypted secret keys
10. Unknown (fallback)

Getting Started

Environment requirements

• Node.js >= 20
• Yarn 1.x

Installation

Clone the repository:

git clone https://github.com/pubky/pubky-ring && cd pubky-ring

Install the dependencies:

yarn install
# For iOS you may also need the following:
cd ios && pod install && cd ..

Run the Application

For iOS:

yarn ios

For Android:

yarn android

If everything is set up correctly, you should see your new app running in your Android Emulator or iOS Simulator shortly provided you have set up your emulator/simulator correctly.

This is one way to run your app — you can also run it directly from within Android Studio and Xcode respectively.

Troubleshooting

If you can't get this to work, see the Troubleshooting page.

🔐 Verifying Releases

Ensure your app-release.apk is authentic and untampered by verifying its GPG signature and SHA256 checksum.

1. Import the Maintainer's GPG Key

gpg --import public-key.asc

2. Verify the APK Signature

gpg --verify app-release.apk.asc app-release.apk

3. Verify the Checksum

gpg --verify SHA256SUMS.asc
sha256sum -c SHA256SUMS

E2E testing (Maestro)

This project runs iOS simulator and Android emulator E2E tests with Maestro.

Prerequisites

• Xcode with an iOS Simulator.
• Android SDK with an emulator.
• Maestro installed locally: curl -Ls "https://get.maestro.mobile.dev" | bash.
• The app built and installed on the target simulator or emulator.

Run tests

yarn e2e:ios
yarn e2e:android

Environment overrides

• HOMESERVER_ADMIN_PASSWORD: required for the custom homeserver flow.

Examples

# Run all iOS flows against the installed app
yarn e2e:ios

# Run all Android flows against the installed app
yarn e2e:android

# Run flows that request a staging invite code
HOMESERVER_ADMIN_PASSWORD=... yarn e2e:ios
HOMESERVER_ADMIN_PASSWORD=... yarn e2e:android