Getting Started

This document is designed to be a basic introduction to Improviz.

Ideally it should get you up and running and familiar with some of the basic concepts.


Pre-built Binary

The simplest way to start is to downloaded and un-archive the pre-built release for your system from the GitHub Releases page. Improviz needs to be run from the terminal because of the way it’s built, but this is easy to do.

If you get a white screen appearing in the top-left then things are looking good.

Depending on the system you’re running on, you may get a prompt asking Do you want the application “improviz” to accept incoming network connections? This is because Improviz runs an HTTP service that’s used for communications between the program and the editor, so you need to allow this.

If you’re on OSX, then you may also get a security warning that won’t let you run Improviz. This isn’t anything to worry about, it’s just because I’m not willing to pay Apple to code sign the app. Open up Security & Privacy settings, go to the General tab, and you should have the option to let Improviz run. Allow this, and then try restarting it from the command line.

If you don’t get a screen appearing, then please raise an issue on the repository and include any error messages that may have been printed out in the console.

Building from Source

If you’d prefer to build from source, then the development documentation should cover all the details.


Once Improviz is running, you need to send code for it to run. The simplest way to do this to test is to use the (very basic) built in editor.

Open your browser and go to http://localhost:3000/editor, then try entering the following. Indentation is done using a single tab.

background(255, 0, 0)

fill(0, 255, 255)
loop 10 times
	rotate(time, 3, time)

You should see ten light-blue cubes rotating on a red background, with the black and yellow text in the top left.


The built in editor is fine for quick tests, but it’s much nicer to work with one that’s a bit more friendly.

There are better clients available for Vim and Atom. There is a very basic client available for Emacs.


If you downloaded the release archive, then you should find there’s a documentation folder with a number of files in it. This should cover everything you need to get going.

You can also find the same documents available on the Improviz website.