Skip to main content

ZefHub connections

ZefHub connections

By default, importing the zef module will attempt to connect to ZefHub automatically. However, this is only possible if your credentials are known (either you have previously logged in, or you have set the ZEFHUB_AUTH_KEY environment variable). When any command that requires ZefHub is run (for example, a requesting a graph by tag, or asking for a new ET or RT) then it will throw an exception if you are not connected to ZefHub.

To login, you should use the login effect. Calling this will start a local HTTP server to perform auth through either a 3rd-party provider (for example GitHub) or an email/password pair. Explicitly, this is the recommended code to run on your first zef session:

from zef import *
from zef.ops import *

login | run

It is possible to provide credentials for login without using the browser login process. ZefDB looks for credentials in the following order:

  1. The ZEFHUB_AUTH_KEY environment variable (plaintext email/password).
  2. The ~/.zef/zefhub.key file (plaintext email/password).
  3. The ~/.zef/credentials file (refresh token).

It is recommended to use the refresh token method from the ~/.zef/credentials file, which is populated via the login effect. However, if you do use a plaintext email/password, it is not communicated directly with ZefHub but instead exchanged for a login token via secure connection with Google Firebase.

To login as a guest user, you can set ZEFHUB_AUTH_KEY to GUEST.

Logging out

To logout, you can use the logout effect. This will also unload all graphs and is therefore RISKY.


When graphs are unloaded, any ZefRef referencing that graph is invalidated. Accessing an invalid ZefRef will cause a segmentation fault.

Alternatively, you can logout by deleting the ~/.zef/credentials file and restarting your python session.