Installing

With Docker

Run Spoletta on one machine with Docker Compose: MySQL, the webapp and the worker that runs agents and scripts, each in a container built from Spoletta's source.

What you need

• Docker with Compose v2: docker compose version prints a version. Docker Desktop has it.
• git, openssl, and access to the Spoletta repository.
• An API key for at least one model provider, such as Anthropic or OpenAI.
• About 4 GB of memory free for the three containers.

Install

1. Get the source

   git clone https://github.com/Nucc/spoletta.git
   cd spoletta

2. Choose the models

   The worker runs agents with pi, and offers the models your pi config names: ~/.pi/agent/settings.json and models.json. If you use pi already, keep yours. Otherwise make both; these offer one OpenAI model:

   mkdir -p ~/.pi/agent
   [ -f ~/.pi/agent/models.json ] || echo '{}' > ~/.pi/agent/models.json
   [ -f ~/.pi/agent/settings.json ] || cat > ~/.pi/agent/settings.json <<'EOF'
   {
     "defaultProvider": "openai",
     "defaultModel": "gpt-5.5",
     "enabledModels": ["openai/gpt-5.5"]
   }
   EOF

   enabledModels lists every model agents may pick, as provider/model; models.json adds providers pi doesn't know, such as a gateway of your own.

3. Write the settings

   Settings go in a .env file next to compose.yaml. Make one with passwords for MySQL and the secret key that seals the model keys and tokens kept in the database:

   cat > .env <<EOF
   MYSQL_ROOT_PASSWORD=$(openssl rand -hex 16)
   MYSQL_PASSWORD=$(openssl rand -hex 16)
   SECRET_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   MySQL takes its passwords the first time it starts, so set them before then. Copy SECRET_KEY to wherever you keep your backups: the webapp won't start without the key that sealed its secrets. See Sealing secrets.

4. Give the worker your model keys

   Export them in the shell you start compose from, which passes them on to the worker:

   export OPENAI_API_KEY=...

   Or skip this, and once Spoletta runs, paste them in Settings, Model keys, where they are kept sealed and survive restarts. See Model keys.

5. Start it

   docker compose up --build -d

   The first build takes a few minutes. docker compose ps shows the three containers, and docker compose logs -f webapp worker what they are doing.

6. Open it

   Go to http://localhost:8080, and build your first flow.

More settings

All go in .env, and take effect with docker compose up -d. The comments in compose.yaml list every one.

Scripts and agents can read GIT_TOKEN and the Sentry and Jira settings too, since they run on the worker with them.

Day to day