Skip to main content

How to: Write an App from scratch

This guide will walk you through the steps for laying the ground for your first SyftBox App.

Requirements:

  • SyftBox

Directory structure​

First, create a directory with the name of your App inside the SyftBox apps directory.

Example:

SyftBox/
├── apps
│  └── my_app <- your new App directory
├── datasites
├── logs
...
info

SyftBox identifies Apps based on their directory name.

App runner script​

Next, create a file called run.sh in your App's directory:

SyftBox/
├── apps
│   └── my_app
│       └── run.sh  <- your App's runner script
├── datasites
├── logs
...
info

SyftBox interfaces Apps through the App runner script: run.sh. Each App needs a runner script that defines what needs to be done whenever your App is initiated.

The run.sh is run every 10 seconds, and it should:

  • prepare the environment
  • build your code, if needed
  • install dependencies, if any
  • run your App
  • cleanup, if necessary

Here is an example of a App runner script for a App written in Python:

#!/bin/sh

# Make sure the script stops when encountering errors.
set -e

# Create a virtual environment, if one doesn't already exist.
if [ ! -d .venv ]; then
  uv venv
fi

# Activate the virtual environment.
. .venv/bin/activate

# Install or upgrade dependencies.
uv pip install --upgrade -r requirements.txt

# Log execution details and run the code.
echo "Running 'my_app' with $(python3 --version) at '$(which python3)'"
python3 main.py

# Deactivate the virtual environment.
deactivate
tip

We recommend using uv as the virtual environment management tool (for Python Apps) because it's fast and makes it simple to run projects in isolated virtual environments, which is ideal for SyftBox Apps.

App code​

Finally, add your App code and configuration files to the App's directory.

For example, in a Python App:

SyftBox
├── apps
│   └── my_app
│       ├── main.py           <-- your app's code
│       ├── requirements.txt  <--
│       └── run.sh
├── datasites
├── logs
...

And that's it! Now you can start develping your App on the SyftBox network!