NAV Navbar


Hello new Bonsai developer!

There are some things you might want to know before you get started. In this section, we’re going to walk you through the components and fundamental ideas of The Bonsai Platform. Read through the Quick Start guide to learn how to get set up with The Bonsai Platform and what you can do with it.

If you’re the type of developer who wants to dive right in and see The Bonsai Platform working, however, skip down to Create Your BRAIN below. We’ll guide you through setting up your first BRAIN with the Cartpole template, how to get that BRAIN training, and then explain what to do with it!

If you’d prefer not to use our web interface, instead you can Use the CLI for Training for a similar guide to this one on your local computer or virtual machine.

The Bonsai Platform

The Bonsai Platform


  • Bonsai Command Line Interface (CLI): is a command line tool that enables you to configure and control The Bonsai Artificial Intelligence (AI) Engine. This is an alternative to using the Web Interface and is not covered in this guide. See how to Use the CLI for Training if you prefer CLI development.
  • Web Interface: is the browser-based tool found at for creating and analyzing BRAINs stored in The Bonsai AI Engine. You can also visualize the BRAIN’s training on this page. This is what we will use for this Quick Start guide because you can get up and running on the Bonsai Platform in just a few clicks!
  • Simulators: are often a complex interactive virtual environment. For this project, you’ll be using a simple simulator from OpenAI. Simulators usually have state, which is a representation of the world inside the virtual environment and receive actions which change that state.


  • Inkling: our special purpose programming language for machine teaching. It expresses the solution to a problem in terms of how you teach the computer to find the solution as opposed to how to calculate the solution. This means that you, the developer, can leverage your domain-specific expertise about the problem space and leverage our expertise about machine learning. To learn more about Inkling, refer to our Inkling Guide.
  • Bonsai Artificial Intelligence (AI) Engine: abstracts away and automates the low-level mechanics of artificial intelligence. Each Inkling program developed is fed into the Bonsai AI Engine in order to generate and train appropriate models (referred to as BRAINs).


  • SDK/Library: can be used after your BRAIN is created and trained. Use with your own application by connecting it to the API generated by the AI Engine using the Bonsai library.
  • APIs: enables AI creators and AI users to interact with the Bonsai AI Engine. To learn more about our APIs, refer to our API Reference.

Ultimately, our platform enables you to build AI agents that work (or play) for you without a deep knowledge of machine learning.

What are BRAINs?

A BRAIN, Basic Recurrent Artificial Intelligence Network, is an individual AI agent, and it is programmed to learn using Inkling. Each BRAIN lives in the Bonsai Artificial Intelligence (AI) Engine which manages and automates much of the lower level complexities of working with artificial intelligence.

The Bonsai AI Engine contains a vast array of machine learning algorithms, manages data streaming and data storage, and provides the efficient allocation of hardware resources. It is built with an infrastructure that supports streaming data efficiently through the system, and it uses a set of heuristics to make choices about which learning algorithms to use to train each BRAIN. The set of heuristics also make it possible for it to choose from any number of possible algorithms, topologies, etc., train all of them in parallel, and pick the best result.

For example, if the BRAIN Server picked Deep Q-Learning, which is a machine learning algorithm, then the system also picks the appropriate topology, hyper-parameters, and initial weight values.

Read more about how the Bonsai AI Engine works in our AI Engine Guide.

What is a simulator?

Brain and Simulator

A simulator is software that simulates an imperative model of a process, transitioning from state to state as actions are applied. Robotics, industrial automation, supply chain logistics, and structural engineering are all domains which use simulators to model the behavior of complex systems.

Deep Reinforcement Learning (DRL) can work with simulated models to train a BRAIN to perform tasks within the modeled system. Tasks can be as simple as “stand this pole upright” or as complex as “learn to walk.”

To be effective, a BRAIN needs to be trained using DRL against a simulated model. The Bonsai SDK allows the DRL system to control your simulator during the training process. Any simulator which has an initial state, and can be incremented through time, can be connected to the Bonsai training system.

Training means teaching a BRAIN to reach a specific outcome in the simulation. The training involves using a specific set of concepts, a curriculum, and lessons, which are described in the Inkling file.

Today, we only support simulators written in Python or C++. To learn more about connecting your own simulator, refer to our Library Reference.

Create Your BRAIN

Open AI’s Cartpole Gym Cartpole Trained

Before you begin, you will need to have access to the Bonsai Platform preview. If you don’t have access yet, request access at

In this guide, we’ll walk you through creating a BRAIN to train the OpenAI Gym environment for Cartpole, a simple balance control problem. The walkthrough of the Inkling code and simulator interface can be found in our Examples and the full source code for you to take a look at is on Bonsai’s GitHub.

If you’d prefer not to use our web interface, instead you can Use the CLI for Training for a similar guide to this one on your local computer or virtual machine.

BRAIN Dashboard

No BRAIN Dashboard

Setup Cartpole BRAIN

The dashboard has a New BRAIN button as pictured. Click on it to create a BRAIN.

Create New BRAIN

Select ‘Cartpole’ from the set of BRAIN templates. The Cartpole simulation can be managed on Bonsai’s servers, so you don’t need to run anything locally on your computer to train this simulation. At this time, you will also be asked to give your BRAIN a name and a description.

Click on the “Create” button which will take you to the BRAIN Details page.

BRAIN Details

BRAIN Graph Untrained BRAIN graph

BRAIN Training Graph

Do not be afraid! You don’t have data yet because you haven’t trained your new BRAIN! That’s the next step. This graph will display each of your concepts to be trained (if you look in the Inkling code you’ll see that Cartpole only has one).

Code Editor Window Code Editor Window

Code Editor Window

The code editor shows you all of the files that are contained within your project and the contents of each file if you click on them on the left.

Your code will automatically compile (if it’s Inkling) and save every few seconds while you are editing. You never need to edit code in the browser if you don’t want to. Check out our CLI Install Guide to install the Bonsai CLI locally, download these files, and run the rest of this guide locally if you want.

Train Your BRAIN

Start Training BRAIN

Trained BRAIN

When you’re done checking out the code editor and ready to start training this BRAIN on the Cartpole simulator, simply click the Start Training button below the graph.

What this is going to do is spin up a container for the AI Engine, connect up to the file, and start the BRAIN training. All with one button!

Training Cartpole for about 15 minutes will give you reasonable performance for this task of balancing a pole on a cart. The longer you train the BRAIN in this case, the longer the cart will be able to balance the pole before it falls over. You can experiment with training for longer but you should be able to see the reward start to flatten out after 10 minutes or so as shown in the picture. Your graphs will vary because the training takes random actions, so don’t worry if yours don’t look like these.

The server will automatically end training once the BRAIN reaches past a certain accuracy, but you will most likely want to stop training before it gets there because there will be diminishing returns for training after about 30 minutes. You can play around with training for 15 mins, 30 mins, or even 1 hour and use your BRAIN to see how well it plays each time!

Click the “Resume Training” button if you wish to continue training on the same version, or start over with a fresh version of the BRAIN by clicking “Start Over”.

Use Your BRAIN

Cartpole Trained

Congratulations on training your first BRAIN! “What do I do with it now?” you may ask.

To use the BRAIN you’ve just trained you’ll need to locally run the python simulator for OpenAI Gym. If this was your own simulation you had written, this would be the part where you hook it up to your application and get predictions of your own!

If you decide to skip this setup or have trouble installing the Bonsai CLI you can get the satisfaction of seeing what the simulation would look like by watching this pole balance on the cart in gif form.

Install Bonsai CLI

Install Bonsai CLI

pip install bonsai-cli

# If you're running python3 on macOS:
pip3 install bonsai-cli

The Bonsai Command Line Interface (CLI) is a command line tool that enables you to configure the Bonsai AI Engine. The CLI is especially useful for automation and connection to other tools. Currently, there are some actions that can only be performed using the CLI, such as getting predictions.

If you already have python installed you should be able to run the python package manager pip to install the Bonsai CLI. Otherwise, check out the CLI Guide Install Prerequisites section to get everything installed and then come back here.

Run Prediction

Download Project Files

bonsai download myCartpole
cd myCartpole

Install Simulator’s Requirements

pip install -r requirements.txt

# If you're running python3 on macOS:
pip3 install -r requirements.txt

The simulator file that you need to run is one of the project files the server created when you made your BRAIN. You can download these project files locally with the download command, and then cd into that folder to look around.

You’ll also want to run the requirements.txt file which contains all of the packages your simulator needs to run. This pip command will make sure all of them are installed, and if not, install them for you.

Use Your BRAIN

python --predict=latest

# If you're running python3 on macOS:
python3 --predict=latest

It’s finally time to run the simulator using predictions from your BRAIN! How well it does depends on how long you let it train. Using your BRAIN involves calling Python on the project’s simulator file, in predict mode, and --predict=latest will use the latest training session that you just ran. You can also specify a number like --predict=1 if you want to predict from a different version of your brain if you have trained it multiple times.

Next Steps

Now that you’ve completed this guide, you can:

Check out Tutorial 1 - Running Simulations and Writing Inkling

It contains all of the information you need to get up and running with your own projects on the Bonsai Platform. You’ll learn:

  • The basics of reinforcement learning
  • How to hook up a simulation to the Bonsai Platform
  • The core components of the Inkling language
  • How to train a BRAIN with custom Inkling code

And we have these other resources that will enable you to maximize your AI development experience: