Getting Started

January 26, 2016


  1. Introduction
  2. Creating your FREE account
  3. Installing the Spacedecode runtime application
  4. Authorise the runtime to access your account
  5. Creating your first project
  6. Adding a vessel
  7. Running the project

1. Introduction

Spacedecode is a platform that gives software developers a complete workflow for building, testing and deploying reliable software. It comes in three parts:

  • Online platform: Accessible via For collaboration & deployment management;
  • Runtime engine: Installable for offline use. For building, testing & managing projects.

2. Creating your FREE account

Note: You may skip this section if you already have a Spacedecode account.

To create your free account, click here. You will be asked to check your email address to activate your account.

Note: Please also check in your spam folder if you cannot find the activation email in your inbox.

3. Installing the Spacedecode runtime application

To install the Spacedecode runtime engine, click here, choose your operating system and follow the instructions. After installing the runtime engine, you will also get a graphical desktop interface and a commandline interface for managing your projects.

4. Authorise the runtime to access your account

To connect your computer to your Spacedecode Online account, you need to login from Spacedecode Desktop. You can do this either through commandline or the UI.


$ spaced login --host=""

You will be prompted for an Access Token, Username and Password. You can generate an access token by logging in to Click on the avatar > Your Settings > Access Tokens > New Token. The token will be printed out once. Copy it before it disappears. See the Security section for more details.

Login via Spacedecode Desktop UI.

Spacedecode Login

If it all goes well, proceed. Else check out the issues page for possible solutions.

5. Creating your first project

Using the command-line, run the command below (replace “<project_name>” with the name of the project).

$ spaced project create <project_name>

Note: Projects can also be created using the UI.

Once created, the project will be available in the workspace with the .proj file extension.

Note: Spacedecode creates a directory SpaceD on the user home directory. We refer to this folder as the workspace and it is where everything you create is stored.


To create a project named helloworld, run the following command:

$ spaced project create helloworld

If it all goes well, the project will now be available in your workspace. For example:

Project in the workspace

Viewed from the UI, your new project appears like this:

Project as seen on the GUI

Read more about projects here.

6. Adding a vessel

Vessels are computing units you can add to your project to run services. Think of a vessel as a version-controllable light-weight virtual machine (or linux container). You can use vessels to run just about anything from web servers to database servers. Vessels allow you to break your project down into multiple services for scalability. Read more about vessels here.

Vessels are created inside a project and they are created from recipes. Recipes are previous instances of a running vessel that were captured to re-use. Learn more about recipes here.

To create your first vessel you need the following:

Using the commandline interface

  • You need to the tag of the recipe you want to create the vessel from. See available recipes here. Vessel tags are in this form: username/name. For example, you might find one like this spacedecode/nginx.

  • You also need to know the tag of the project to which you want to add the vessel. The project tag has the same form as the recipe tag.

Using the graphical interface

  • You only need to know the software you want to run as a base. For example creating a vessel running wordpress, you just need to use wordpress as a search query on the dropdown shown below.

  • You also need to select the correct project.

Create the vessel now

Using the commandline, run the following command:

$ spaced vessel create <vessel_name> -p <project_tag> -r <recipe_tag>

NB: Replace the tags with actual values.

If I want to add a vessel to the project we created above, run the following command:

$ spaced vessel create web -p sithembisok/helloworld -r sithembisok/nginx

NB: Note that my username is sithembisok. You will have to replace sithembisok with your username.

This is how you create a vessel from the graphical interface:

Selecting a recipe

Important! The recipe autocomplete searches for recipes both in the local repository and the central repository at This works best if you have an internet connection.

This is how the vessel looks like on the workspace:

Vessel in the workspace

Important! All vessels are represented as folders with a .vsl file extension.

7. Running the project

Since you now have at least one vessel inside the project, you can now run it. Here are our expectations for this part of the exercise:

  • Since we created a vessel web.vsl from the sithembisok/nginx recipe, we expect to have Nginx running when we fire up the project. We will know it’s running by visiting http://localhost or on the web browser and we should see something.

  • Since we only have one vessel inside the project, starting it will change the entire project’s status to RUNNING. See how we check that below.

Okay, let’s go for it. To run the project, run the following command:

$ spaced project start sithembisok/helloworld

Sample response:

web starting...
Vessel started successfully
web started
Project started successfully

To see if the project started successfully, enter http://localhost on your web browser as per our expectations above and you should see a page similar to this (differs depending on the recipe used).

Nginx default page

You can also run the project from the graphical interface. Locate the power button when you select the project. Now that the project is already running, the power button and all status indicators for the project are green in color.

Running project in the GUI

Please note: You can also see which projects are running by running this command:

$ spaced project list

You will see something like this:

Project list from CLI

See also

comments powered by Disqus