The Toshi Developer Hub

Welcome to the Toshi developer hub. You'll find comprehensive guides and documentation to help you start working with Toshi as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Creating a Toshi App

Creating a new Toshi app can be accomplished in as little as 5 minutes. This guide will help you through the process.

1. Fork the starter app

Fork the javascript sample app and git clone it to your local computer.

$ git clone
$ mv toshi-app-js my-app
$ cd my-app
$ git remote rename origin upstream
$ # create an empty repository on your github account
$ git remote add origin
$ git push

The starter app will format all messages properly using the SOFA Protocol and end-to-end encrypt them with Signal so you can focus on the bot logic.

2. Generate a 12 word seed

Visit our seed generator page. This generates a random 12 word phrase that forms the basis of the Ethereum wallet behind your app. It will also display your app id and payment address for reference.

3. Get your app running locally

Now we're going to use Docker to boot up a local instance. First, make sure that you have the latest version of Docker installed.

You'll need to create a docker-compose.yml file and enter the environment variables from the seed generator.

You can read about the available configuration variables here

$ cp docker-compose.yml.sample docker-compose.yml
# open docker-compose.yml with your favorite editor and add the env variables
$ docker-compose up

4. Connect to your app

Your Toshi Dev Android or iOS client should now be able to chat with the Toshi app running locally on your computer.

Open the Toshi Dev app on your phone, and search for the username of your new app from the 'favorites' tab. Alternatively, you can scan the QR code on the seed generator page from above to add your app as a contact.

You can now start chatting with your app!

5. Customize your app

You are now ready to start modifying your app and adding your own logic. Try changing one of the text responses in the sample app and save the file (docker should automatically restart the bot.js process on your machine when it detects a change).

For example, you can try adding a new response option with something like this:

function onMessage(session, message) {
  session.reply("Hello Toshi!")

If you're going to install any new Node packages, you'll need to rebuild the bot container.

$ docker-compose build bot # or docker-compose up --build

If you want to pull down changes from the original toshi-app-js repository in the future, you can do so like this.

$ git pull upstream master
$ # if there are any database changes in new versions, you may need to drop/rebuild the local database
$ docker-compose down -v # v flag will destroy the anonymous volume that holds your postgres db
$ docker-compose up

What's Next

Learn about the various components of a Toshi app.

App Components

Creating a Toshi App