The Blockstack Browser
Switch branches/tags
Clone or download
Failed to load latest commit information.
.circleci update cirlce image to match .nvmrc Sep 20, 2018
app Merge pull request #1718 from blockstack/feature/missing-profile-on-r… Oct 24, 2018
corsproxy default bind the cors-proxy to localhost Mar 14, 2018
docs Changes for the documentation site Sep 13, 2018
flow-typed/npm Merge develop in. Aug 14, 2018
maintainers Changes for the documentation site Sep 13, 2018
native Bump version to v0.34.2 Oct 26, 2018
test Merge branch 'feature/dislay-social-proofs-verification' of git://git… Oct 24, 2018
utils remove webp script Jul 3, 2018
.babelrc add in dynamic import babel plugin for tests Sep 25, 2018
.eslintignore [test] upgrade to nyc+mocha, use test/, add rewire Jun 28, 2018
.eslintrc bump dep versions for testing suite deps for babel-7 Sep 19, 2018
.flowconfig modify redux flow type to support thunk Jun 27, 2018
.gitignore fix conflicts Jul 3, 2018
.npmignore add in auth page; fix routing history; upgrade dependencies Nov 29, 2016
.nvmrc update deps, update nvmrc version to latest LTS, add back in mangle r… Sep 20, 2018
.nycrc bump dep versions for testing suite deps for babel-7 Sep 19, 2018
.prettierignore remove old files, cleanup, format ui components, start lint May 29, 2018
.prettierrc remove old files, cleanup, format ui components, start lint May 29, 2018 Fixes broken link to /issues Feb 23, 2018
Dockerfile remove package-lock changes, remove comments from Dockerfile Sep 5, 2018 add in Mozilla Public License Version 2.0 Nov 3, 2016 Update readme badges. Aug 29, 2018
firebase.json update firebase settings Dec 1, 2016
now.json start route splitting and other perf updates Jun 29, 2018
package-lock.json package-lock changes. Oct 26, 2018
package.json Bump version to v0.34.2 Oct 26, 2018
webpack.config.js update name of worker output Sep 27, 2018

Blockstack Browser CircleCI branch BrowserStack Status License Slack

The Blockstack Browser allows you to explore the Blockstack internet.

Table of contents


Download the latest release



Please note these instructions have only been tested on macOS 10.13

  1. Download and install the latest release of Blockstack for Mac.
  2. Start Blockstack
  3. Option-click the Blockstack menu bar item and select "Enable Development Mode"
  4. Clone this repo: git clone
  5. Install node dependencies: npm install
  6. Run npm run dev


  1. Clone this repo: git clone
  2. Install node dependencies: npm install
  3. Run npm run dev-proxy to start the CORS proxy
  4. Run npm run dev

Note: npm dev runs a BrowserSync process that watches the assets in /app, then builds them and places them in /build, and in turn serves them up on port 3000. When changes are made to the original files, they are rebuilt and re-synced to the browser frames you have open.


Common problems and solutions:

  • The sign-in page does not load: These instructions run the Browser in development mode, which uses a different port (3000) than the production mode (8888). However, existing applications will direct you to http://localhost:8888 on sign-in. You will need to manually edit the URL to change 8888 to 3000 and refresh the page.

  • The sign-in page does not load with localhost:3000: If you have taken the above step and the page still does not load, check your auth= query parameter. If it starts with any number of / characters, remove them and reload the page. For example, if your auth= query looks like auth=///abcdef..., then you will need to change it to auth=abcdef....

Building for macOS

  1. Make sure you have a working installation of Xcode 9 or higher & valid Mac Developer signing certificate
  2. Make sure you have an OpenSSL ready for bottling by homebrew by running brew install openssl --build-bottle
  3. Make sure you have hg installed by running brew install hg
  4. Run npm install nexe -g to install the "node to native" binary tool globally
  5. Open the Blockstack macOS project in Xcode and configure your code signing development team (You only need to do this once)
  6. Run npm run mac to build a debug release signed with your Mac Developer certificate

Note: You only need to run nexe once but the first build will take a while as nexe downloads and compiles a source copy of node. Then it creates and copies the needed proxy binaries into place and copies a built version of the browser web app into the source tree.

Note: This has only been tested on macOS High Sierra 10.13

Building a macOS release for distribution

  1. Ensure you have valid Developer ID signing credentials in your Keychain. (See for more information)
  2. Follow the instructions in the above section for building for macOS.
  3. Open the Blockstack macOS project in Xcode.
  4. Select the Product menu and click Archive.
  5. When the archive build completes, the Organizer window will open. Select your new build.
  6. Click "Export..."
  7. Click "Export a Developer ID-signed Application"
  8. Choose the development team with the Developer ID you'd like to use to sign the application.
  9. Click "Export" and select the location to which you would like to save the signed build.

Building for the Web

  1. Make sure you've cloned the repo and installed all npm assets (as shown above)
  2. Run npm run web

Building for Linux (dpkg)

  1. Install fpm
  2. Run ./native/linux/
  3. A .deb package will be placed in ./native/linux/dist/


We do project-wide sprints every two weeks and we're always looking for more help.

If you'd like to contribute, head to the contributing guidelines. Inside you'll find directions for opening issues, coding standards, and notes on development.


The Browser uses log4js for logging. The macOS app uses macOS's unified logging API, os_log for logging.


On macOS, the Browser sends log events to the macOS app's log server. These are then included in macOS's unified logging API. You can view logs by starting

To see only Blockstack process logs, filter by process by typing process: Blockstack in the search box. You can also filter for only log entries proactively generated by the BLockstack project using this query: subsystem:org.blockstack.portal subsystem:org.blockstack.core subsystem:org.blockstack.mac If you'd like to see more detail, enable the inclusion of Info and Debug messages in the Action menu. Please note that in our experience, doesn't always show debug messages in real time and only shows them when doing a log dump as described below.

Sending logs to developers

Blockstack logs are included in macOS's unified logging system. This allows us to easily collect a large amount of information about the user's system when we need to troubleshoot a problem while protecting their privacy.

  1. Press Shift-Control-Option-Command-Period. Your screen will briefly flash.
  2. After a few minutes, a Finder window will automatically open to /private/var/tmp
  3. Send the most recent sysdiagnose_DATE_TIME.tar.gz file to your friendly developers.

The most important file in this archive is system_logs.logarchive, which will include recent system logs including Blockstack's logs. You can open it on a Mac using The other files include information about your computer that may help in diagnosing problems.

If you're worried about inadvertently sending some private information, you can select the log entries you'd like to send inside and copy them into an email or github issue. To help us debug your problem, we ask that at a minimum you enable Info and Debug messages and filter by process: Blockstack.

More technical users (with admin permission) can use the sysdiagnose command to generate a custom dump of information.

Tech Stack

This app uses the latest versions of the following libraries:

And a few other smaller modules (these can be found in package.json).


This repository is maintained by


Run all tests in the test/ directory with the npm run test command. A single file can be run by specifing an -f flag: npm run test <PATH_TO_TEST_FILE>.

Note: When running tests, code coverage will be automatically calculated and output to an HTML file using the Istanbul library. These files can be seen in the generated __coverage__/ directory.

App Development

Run the browser in the Blockstack Test Environment

When developing apps, the browser can be run in a docker test environment that is backed by the regtest bitcoin network, hence no real money involved.

The easiest way to get that setup is through docker containers for the api, the browser and the cors-proxy. There is a docker-compose.yaml file published in the Blockstack todo app repo that does this. To use it, first install Docker and stop any running Blockstack applications (blockstack-browser or blockstack api) then:

$ docker-compose up -d

This brings up

  1. a blockstack-core api node that is backed

    • by a bitcoind instance running regtest and
    • by a blockstack-core node built from the test chain.

    The initialization script generates 50 BTCs for the core wallet.

  2. a blockstack-browser node. It uses bitcoin addresses that are mapped to regtest bitcoin addresses.

  3. a cors-proxy to bypass origin policy issues.

The easiest way to work with this setup is in Incognito mode in your browser. Once the images have been pulled down and the containers are started you can open http://localhost:8888.

Choose the Advanced Mode setup and enter the API Password as blockstack_integration_test_api_password

Common Tasks

  • You can send bitcoins from the core wallet to the browser wallet by opening the hidden url http://localhost:8888/wallet/send-core

  • You can inspect the mapped bitcoin addresses from the browser node to the regtest address by looking into the log file of the api node (execute bash in the api container and look at /tmp/blockstack-run-scenario.blockstack_integration_tests.scenarios.portal_test_env/client/api_endpoint.log).

  • You can inspect the api password by looking into the client.ini file of the api node (execute bash in the api container and look at /tmp/blockstack-run-scenario.blockstack_integration_tests.scenarios.portal_test_env/client/client.ini)

  • You can verify the blockstack version of the api node by running curl localhost:6270/v1/node/ping