Unicity AgentSphere: A Web3 Wallet and Messaging Platform on Nostr

What AgentSphere Solves and Who Uses It

AgentSphere is the wallet and agent frontend for the Unicity network, a Web3 platform using fast, low-cost state transitions for token operations. It combines four functions in one application: a crypto wallet for token transfers and balance tracking, direct messaging via Nostr, public and private group chat via the NIP-29 relay protocol, and an agent tab that loads any external dApp as an iframe inside the wallet UI.

The project targets two groups. The first is Unicity network users who need a single app for managing tokens, receiving payments, and communicating with other network participants via Nostr DMs. The second is dApp developers who want to integrate with the wallet through the Connect protocol, which allows their application to request wallet operations (send, sign, DM flows) from inside an iframe or a popup.

The README describes AgentSphere as the wallet side of the Sphere Connect protocol. External dApps connect to it rather than running wallet logic themselves, keeping key management and transaction signing inside the wallet boundary.

Architecture: SDK Adapter, Nostr Backend, and State Management

The application is built on React 19 with TypeScript and Vite 7. TanStack Query v5 handles server state, React Router DOM v7 manages routing, and Tailwind CSS 4 handles styling. Framer Motion drives UI animations.

All wallet operations go through @unicitylabs/sphere-sdk, which handles the Unicity L3 state transitions, Nostr identity, and IPFS sync. The application's sdk/ directory contains a React adapter layer over this SDK, organized into three groups of hooks: core hooks (useSphere, useWalletStatus, useIdentity, useNametag, useSphereEvents, useIpfsSync), payment hooks (useTokens, useBalance, useAssets, useTransfer, useTransactionHistory), and communication hooks (useSendDM, usePaymentRequests).

The Nostr protocol powers private direct messages. Group chat uses the NIP-29 relay specification, connecting to a dedicated relay at wss://sphere-relay.unicity.network. The application monitors unread message counts and handles group discovery, join, and leave operations.

The Docker image uses a build-once, promote-many pattern. Vite bakes VITE_* environment variables into the bundle at build time, so runtime configuration is handled through placeholder substitution: the Dockerfile bakes sentinel values (like __RUNTIME_SPHERE_API_URL__) and a startup script rewrites them from container environment variables before the server starts.

Running AgentSphere Locally and with Docker

Running the development server requires Node 20 or newer. Clone the repository, install dependencies, copy the example environment file, and start the dev server:

npm install
cp .env.example .env    # Configure environment variables
npm run dev              # Start dev server at http://localhost:5173

The .env.example file sets VITE_SPHERE_API_URL to localhost:3001 by default. For wallet API custody, set VITE_WALLET_API_URL; without it, the application uses the legacy local-custody composition. The staging Unicity backends are available at CORS-enabled URLs listed in the example file if you want to test against a live network without running local services.

The full set of development commands:

npm run dev          # Development server
npm run build        # TypeScript compile + Vite production build
npm run preview      # Preview production build
npm run lint         # ESLint
npm run test         # Vitest watch mode
npm run test:run     # Vitest single run

For a production-style deployment, Docker Compose runs the containerized application on port 3010:

docker compose up        # Runs on port 3010

The docker-compose.yml defaults to staging API endpoints and has SUBSCRIPTION_ENABLED and PAID_PLANS_ENABLED both set to false, meaning subscription-gated features are dormant in the default Docker configuration.

The Connect Protocol and Deep Link System

AgentSphere implements ConnectHost, the wallet side of the Sphere Connect protocol. External dApps can establish two connection modes: iframe mode (the dApp is embedded in AgentSphere as an iframe and communicates via PostMessageTransport) and popup mode (the dApp opens AgentSphere as a popup window and the user approves the connection explicitly).

In both modes, the dApp requests specific permission scopes. The user approves or rejects these scopes before the dApp can trigger send, sign, or DM operations. The key components handling this are ConnectPage at the /connect route, ConnectProvider, and ConnectionApprovalModal.

Sphere also supports a custom URL protocol for inter-app linking within DMs: unicity-connect://. When a dApp sends a unicity-connect:// URL in a DM, AgentSphere renders it as an interactive button with two choices: open the URL as an iframe agent inside the wallet, or open it in a browser tab. The protocol conversion strips the custom scheme and replaces it with https://, with localhost and 127.0.0.1 mapping to http://.

The deep link rendering is handled in three layers: src/utils/deepLinkHandler.ts for protocol conversion and global click handler registration, src/utils/markdown.tsx for the DeepLinkButton component and link detection, and src/hooks/useDeepLinkNavigation.ts for the Sphere-side navigation handler.

Limitations: Private License, Feature Flags, and Backend Coupling

The README explicitly states that AgentSphere is a private project under a Unicity Labs license. This means the code is available on GitHub for reference but is not open for redistribution, forking, or use outside the Unicity ecosystem without permission from Unicity Labs. This is a hard constraint for any developer who wants to build a derivative project.

Two subscription-related feature flags (VITE_SUBSCRIPTION_ENABLED and PAID_PLANS_ENABLED) are documented as shipping dormant. These are build-time feature flags managed through a runtime configuration file rather than Vite's normal environment injection. The README notes that because Rollup prunes conditional branches at build time, these flags cannot use the standard placeholder mechanism and are instead written to /runtime-config.js at container startup. Turning on subscriptions requires setting SUBSCRIPTION_ENABLED=true in the container environment.

The application is tightly coupled to the Unicity network's backend services. The .env.example shows two API endpoints (VITE_SPHERE_API_URL for the quest API and VITE_WALLET_API_URL for the wallet API) plus an aggregator key. Running entirely offline or against a different network requires rebuilding these integrations, which are embedded in the @unicitylabs/sphere-sdk dependency rather than exposed as configuration.

Group chat relies on a single dedicated relay (wss://sphere-relay.unicity.network). The README does not document fallback relays or how the application behaves if that relay is unavailable.

Comparing AgentSphere to Standalone Wallet Approaches

MetaMask is the most widely used Web3 wallet in the browser. It is a browser extension that manages private keys and signs transactions for Ethereum and EVM-compatible networks. The primary difference in approach is scope: MetaMask focuses on key management and transaction signing, providing a permission layer between dApps and the user's keys. It does not include messaging, group chat, or an agent iframe system.

AgentSphere takes the opposite approach by embedding all of these functions in a single React application. The wallet, the messaging layer (Nostr), the group chat (NIP-29), and the dApp agent interface are all part of one codebase communicating through shared state. This reduces the surface area where a dApp needs to integrate multiple tools, but it also means AgentSphere is network-specific rather than a general-purpose wallet.

For developers building on Ethereum or EVM networks, MetaMask and its SDK are the established choice. AgentSphere exists specifically for the Unicity network and its state transition model, and the README does not describe support for other networks or key formats. A developer building a dApp on Unicity would use the Connect protocol to reach AgentSphere; a developer building on another chain would not.

Editorial conclusion

AgentSphere is the right starting point for developers building on the Unicity network who need a reference implementation of the Connect protocol, Nostr-based messaging, and NIP-29 group chat in a single application. Because the project carries a private license, forking or using the code outside the Unicity ecosystem requires permission from Unicity Labs. Anyone evaluating the project should verify the current status of the staging API endpoints and the subscription feature flag, since both affect whether a local run reflects production behavior.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. unicity-sphere/sphere on GitHub