How to develop for the SAFE Network (draft)

Whether you are building an application or a website, the first thing you’ll need is a SAFE Browser that is built for mock-routing.

What is mock-routing and why?

When the SAFE Browser, or another application, is built with mock-routing enabled, it’s not connecting to a live network, it’s interfacing with a local database that is created on your system to simulate network operations.

This saves a great deal of time and provides a safe space for your application or website to initially test operations.

Building the SAFE Browser for mock-routing

If you’d like to build your own browser, you can go to the SAFE Browser repository and follow the instructions in the README.

The first thing you need to do is make sure you have an environment variable of NODE_ENV set to dev.

  • On a Linux-based OS or on macOS, you can create a shell variable that will last as long as the shell session, simply with export NODE_ENV=dev

  • On Windows, using Powershell, you may set a shell variable that also only lasts as long as the shell session with, $env:NODE_ENV = 'dev'

Then follow the steps in the repo’s README, summarised as follows: yarn && yarn run build

Before running yarn run package, run yarn start first to verify that the browser was built successfully and to check for errors in your terminal. Then you can spend the time to package a browser binary with yarn run package.

At this point, you have a running SAFE Browser that is solely interfacing with mock-routing on your system. This is enough if you are only developing a website for the SAFE Network.

Developing a SAFE website

Clone this repository, cd into safe_web_api_playground, and follow the instructions in the README to get server started.

Open a new tab in the SAFE Browser and navigate to localhost://p:3003, where you’ll be able to view the site and work with the SAFE Web API. Try making changes in the code and see how gulp is watching for file changes so that you don’t have to restart the server. Just refresh your browser tab.

Using this repo as an example of how to quickly develop your own site:

  • Run npm init in your own project folder, follow command-line instructions, and then observe your newly created package.json file

  • Run npm install --save express body-parser

  • Copy gulpfile.js into your project folder, if you’d like to automate tasks like restarting the server and concatenating JS modules. Otherwise you don’t need it but it does speed up development. If you do want to use it, be sure to npm install gulp -g

  • Copy the index.js file into your project folder. This program serves your index.html and broadcasts it on port 3003.

If you are working with gulpfile.js, simply run gulp.

If you are not working with gulp, simply run node index and your server will start.

Building applications for mock-routing

If building one of the SAFE example apps, like Web Hosting Manager or SAFE Mail Tutorial, simply set NODE_ENV=dev, using the same suggestions as above for building a SAFE Browser.

If building your own application, there are a number of options depending on what you need. Take a look at this very basic Electron application,, which uses the SAFE App Node.js library as a dependency to connect to the network.

Your application will send requests to the authenticator client, which is integrated with the SAFE Browser, and listen for responses.

Mock-routing errors

At some point you may start running into errors like Access denied... or Entry does not exist..., while using the Web API. If this is the case, you can delete your local MockVault file and restart your SAFE Browser.

The MockVault file is stored in a different path depending on your platform. Use this document to find where it is on your system.

Moving to a test network

After testing and getting familiarised with network operations on mock-routing, the next step is to move your application to a test network, which is live but is not the public SAFE Network. This phase will help pick up errors that may not have been able to be simulated in mock-routing.

The MaidSafe developer team will have binaries available for download for the SAFE Browser and for the SAFE App Node.js library that specifically connect to a developer test network. Hosting your application on a test network is a good way to get other users to test your application.

The latest test network is Alpha 2. See this topic for more info.

Another option is to run your own local test network. See this topic for more info.

Moving to the public SAFE Network

Once you are done with mock-routing and the test network, your application, if using the SAFE App Node.js library to interface with the network for example, will need a library that is set to connect with the primary live network.

There is no live network yet. See MaidSafe’s roadmap for more information on upcoming releases.


@hunterlester @bochaco I’ve built to debug with mock and am having a problem using a different web server: did get checkout master, git pull and npm burnthemall in my existing clones of safe_browser and Hunter’s repo of safe_dom_api_playground before repeating the build steps.

Not tried gulp yet, but I’m working in an existing project and don’t want to add unnecessary stuff to it so I’m using ws web server (on debian 8).

So I’ve got the mock browser working and using hunter’s repo for the playground both appear to work. If I kill gulp and then go to my own project…

I run a web server on port 8000 (or 3003) and then in SB I access localhost://p:8000 (or 3003) I get strange behaviour:

  • the browser window is black
  • the browser TAB correctly shows the Title from my index.html
  • I can access and load individual files such as localhost://p:8000/drink.jpg
  • the debugger shows that the JavaScript code is running (lots of console.log o/p) and no errors
  • the debugger offers to show me the contents of both JS and HTML files (e.g. index.html) but the tabs I open to show those files are always blank. No JS, no HTML, and as mentioned, the browser window itself shows a black page.
  • debugger > Select Element - cursor doesn’t react when moved over the browser window

This is very strange. I was able to debug this exact project live on Test 17. Will check what happens on Test 18 but posting this now and will update… YES: works live on Test18, you can visit it here: safe://myfd

Issue: after doing the above with SB mock, the test18 web host manager didn’t work - it starts but its window remains blank/white and nothing happens. I rebooted my machine and then all was ok, so running the mock browser messes up running non-mock apps and/or browser.

@happybeing, you will have to set NODE_ENV=dev
Before running the burn the mall command or while trying to build the browser for mock following the instructions from the readme. Export and set the NODE_ENV variable, so that it gets applied at all stages of the build process. Can you run burnthemall command after setting the NODE_ENV and try once more please?

@Krishna I already did export NODE_ENV=dev in each terminal before anything else.

As mentioned, SB mock and playground mock appear to work. I haven’t done anything with them but they look fine - ie the playground loads and clicking some of the APIs works.

The symptoms suggest to me that everything is working except that the website’s window is not internally hooked up properly inside the browser. My app javascript appears to be running without problems - just the browser’s website window not functioning as expected.

When you run an instance of a browser, it register the auth URI scheme in your system overwriting any previous registration of it. So if you ran the browser binary we delivered and then you ran your own version built with mock, the URI scheme is then registered to launch your browser. So in your case, when you run a desktop app which sends an auth request to the browser, the system will direct it to your browser built for mock.
Now, I’m not sure what you meant by after restarting everything worked, because if you have the browser with mock registered in the URI scheme, then you need your app to be also built with mock (see the corresponding README files for email and web-hosting app to do this), so if you are running you the web-hosting app binary we released against your browser built with mock, it won’t work.
To sum up, make sure your browser and desktop apps are all either built for mock, or all built for using the network, otherwise they won’t work.

1 Like

Thanks Gabriel, that explains it. The ‘restart’ referred to my pc, but I guess the difference was probably running the corresponding browser (re-registering itself) before the app.


The newest binaries support mock routing, right? When I go to localhost://p:3003/ with the safe web api playground it doesn’t connect to the actual test network as far as I can tell.

From this tutorial though, I get the impression that you have to build the browser yourself to get a binary that support mock routing.

If you just use the release version downloaded from github you are interacting with the network

I see. In that case maybe it would be a good idea to release binaries that support mock routing also, either through a command line argument or something or as a standalone developer browser.

I’ve built the browser, but it was a bit of a hassle and I had to download lots of dependencies that I don’t need for anything else, so prebuilt binaries would make it easier for people to get started, especially on Windows.

1 Like

Hi. During browser build, when I do npm start, it turns out there is “gconf” library required by the browser. I haven’t seen any lib requirements in README, so it could help. Also, when I try to do npm run package I get error that is not available. I run Arch Linux and here readline version is already 7.0.

Great tutorial @WhiteOutMashups. When I start the browser, I get this error:

Does anyone know how to fix it?

Also, does the Safe browser running with the mock network remembers anything between launches of the browser? Like credentials and uploaded data?

EDIT: also, I keep downloading safe_proxy.pac for some reason, anyone know how to stop it?


That’s because you are building the browser to use the mock, but the safe_client_libs libraries you are using are built for connecting to the real network. Try pulling the latest code from the browser’s master branch and run yarn run burnthemall to build it (you may need to install yarn globally if you don’t have it yet), you can then run it with yarn start.

Make sure you set the env var to dev, e.g. in linux export NODE_ENV=dev

Yes it does, the mock is a file, and it’s not cleared when the browser is restarted.


Perfect, that worked, thanks!

Any idea why my normal browser (chrome) keeps downloading safe_proxy.pac whenever I reload a page inside the safe browser?

1 Like

It’s probably because you have the automatic proxy from Alpha 1 configured in your OS. Try to remove it :slightly_smiling_face:

1 Like

Nice catch @frabrunelle, thanks!

1 Like

Hi again, question about the web hosting manager. When I run it, I see the SafeBrowser go in focus but the authorization popup doesn’t appears. In the developer console of the SafeBrowser this message appears:

I used NODE_ENV=dev to build the manager and the browser to use the mock routing.

Does anyone have an idea on how to fix it?

EDIT: When I debug the browser, the url the function create(opts) uses (line 1500) is “/home/dav/projects/safe_browser/app” and it seems to not be working when parsing it into “new URL”.

EDIT 2: If I write in the console : new URL(“safe-auth:/home/dav/projects/safe_browser/app”), it successfully creates a new URL object. So it appears that for some reason its missing the protocol in the url. I’m on Ubuntu btw.

Hope this helps.

@hunterlester @bochaco can one of you guys update the OP with build instructions based on yarn (only minor change but will lead people astray if they try to use npm).

Also note, I had to nuke my build directory to switch from npm to yarn, but when I did the yarn mock build was perfect (Debian 8 & Test 19 master).


Sure, I just updated the OP with build instructions based on yarn instead of npm :slightly_smiling_face:


Pretty sure this worked before:

$ git clone
Cloning into 'safe_web_api_playground'...
remote: Not Found
fatal: repository '' not found

But now I seem to have to:

$ git clone
Cloning into 'safe_examples'...
remote: Counting objects: 4549, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4549 (delta 0), reused 0 (delta 0), pack-reused 4546
Receiving objects: 100% (4549/4549), 6.01 MiB | 554.00 KiB/s, done.
Resolving deltas: 100% (2886/2886), done.
Checking connectivity... done.
1 Like

@Krishna I still have this issue (now with the Test 19 master re-cloned and re-built browser), any ideas:


1 Like