Ursula Configuration Guide

Before continuing, Verify your nucypher installation and entry points are functional:

Activate your virtual environment and run the nucypher --help command

$ source nucypher/bin/activate
(nucypher)$ nucypher --help

You will see a list of possible usage options (--version, -v, --dev, etc.) and commands (status, ursula). For example, you can use nucypher ursula destroy to delete all files associated with the node.

If your installation in non-functional, be sure you have the latest version installed, and see the Installation Guide

2(a). Configure a new Ursula node

Decentralized Ursula Configuration

(nucypher)$ nucypher ursula init --provider-uri <YOUR PROVIDER URI> --network <NETWORK NAME>

Replace <YOUR PROVIDER URI> with a valid node web3 node provider string, for example:

  • ipc:///tmp/geth.ipc - Geth Development Node (IPC; Note: Also use --poa flag)

  • http://localhost:7545 - Ganache TestRPC (HTTP-JSON-RPC)

  • ws:// - Websocket Provider

2(b). Configure a new Ursula node

Federated Ursula Initialization

(nucypher)$ nucypher ursula init --federated-only --network <NETWORK NAME>
  1. Enter your public-facing IPv4 address when prompted

Enter Nodes Public IPv4 Address: <YOUR NODE IP HERE>
  1. Enter a password when prompted

Enter a password to encrypt your keyring: <YOUR PASSWORD HERE>
  1. Connect to a fleet

(nucypher)$ nucypher ursula run --teacher-uri <SEEDNODE_URI>
  1. Verify Node Connection

This will drop your terminal session into the “Ursula Interactive Console” indicated by the >>>. Verify that the node setup was successful by running the status command.

Ursula >>> status
  1. To view a list of known nodes, execute the known_nodes command

Ursula >>> known_nodes

You can also view your node’s network status webpage by navigating your web browser to https://<your-node-ip-address>:9151/status.


Since nodes self-sign TLS certificates, you may receive a warning from your web browser.

  1. To stop your node from the interactive console and return to the terminal session:

Ursula >>> stop
  1. Subsequent node restarts do not need the teacher endpoint specified:

(nucypher)$ nucypher ursula run