Common Concepts

The section provides more detailed information on how to deploy hardware with Sabana

Build, Deploy, Run

The sabana platform allow developers to quickly package and ship hardware code to FPGAs. There are three majors steps involved:
  • Building images from hardware source code (Verilog/C++)
  • Deploying instances from these images
  • Running programs on top of deployed instances
You probably saw this pattern in the Quickstart; this was intentional. In the following sections we will go in more depth on each of these three processes for different languages and flows.
We are eager to support multiple hardware languages and flows. If your favorite language/flow is not here yet, please let us know in our Discord community

Creating images

Overall the process of creating a new image can be summarized as follows:
  • Create a new project
  • Choose the interfaces required by the project
  • Integrate your code into the new project
    • You can also think of this step as connecting your hardware to the image shell
  • Push the project to Sabana for it to be built into an image

Identifying images

Images in Sabana are identified using a triple of user, image name, and a tag.
This triple will typically look like this:
# <user>/<name>:tag
This triple allows you to:
  • Share your image with others
  • Use images created by others
  • Use or keep different versions of a given image


Once an instance has been deployed the platform will return a URL. This URL will effectively be the handler that can be used to interact with the instance. There are two ways to deploy instances in Sabana.

Deploying with the CLI

The CLI tool can be used to deploy instances.
[email protected]:$ sabana up robot/hello_world:0.1.0
🎉 robot/hello_world:0.1.0 is ready ➡ ""
[email protected]:$ sabana down
✔ is down
This is useful when one wants to keep an instance running, however a downside of this approach is that one has to remember to terminate the instance, otherwise you may run out of deploy minutes from your allowance.
The most convenient way to deploy images is to use the Sabana Python SDK

Instance hosts

Every instance is comprised by two elements:
  • Instance host
  • Hardware module
The hardware module is in essence your hardware, the one described by the image. This hardware is connected to the instance host, for the purposes of controlling and communicating with the hardware.

Python SDK

The Python SDK is a collection of classes that allow you to interact with Sabana in a programmatic way, specially for the purpose of deploying instances and running programs.
It is comprised of the following modules:
Sabana's programming model follows a request's paradigm:
  • Requests are prepared by the client and submitted to the instance as a program
  • Instances execute these programs
  • Instances return a list of responses for each request that requires it
When we create a project a test script is also created. The whole script is self contained as it has all the necessary elements to deploy an instance and test its behavior.

Deploying with the Python SDK

The most convenient way to deploy instances is by using the Instance class of our Python SDK. You can use Python to programmatically deploy an instance, interact with it, and then terminate it:
# create program
program = Program()
program = populate_requests(program)
# deploy instance
inst = Instance(image_file="robot/hello_world:0.1.0", verbose=True)
# run program
responses = inst.execute(program)
# terminate instance
Notice how we are conveniently using the information from the project file to create the instance handler.
When a new project is created you get a set of files to be used as starting point to get started!


There are two main types of examples in Sabana:
  • Examples generated by the Sabana CLI tool
    These can easily be used as starting point for projects that use similar interfaces.
  • Examples from our GitHub repository
    These are good sources of inspiration for more complex projects.
All the code for our examples can also be found in our examples repository in GitHub: