Shuffle: a self-hostable SOAR platform where security teams build the workflows themselves

What Shuffle automates, and who it is actually written for

Shuffle describes itself as an open source automation platform built for and by security professionals, and the GitHub topics name the category outright: soar, orchestrator, security-automation, mitre-attack, openapi. The README adds that the design has service providers and MSSPs in mind, which is the detail that separates it from a personal automation script. A single analyst can build a phishing triage workflow, but the same workflow can be packaged, shared across an organization, and offered to a client without rewriting it.

There is a small inconsistency worth naming when you first look at the repository. GitHub reports the primary language as JavaScript, yet the README's own repository map describes a Golang backend webserver and a ReactJS frontend. Both are true in different places: the workflow editor and its cytoscape graph view are a large front end, while the API, the app SDK and the execution machinery sit in Go. Anyone estimating the size of the codebase should look at `backend/go-app` and `frontend/` separately rather than trusting the single language label.

The feature list on the README is short enough to take at face value: a workflow editor, an app creator that reads OpenAPI definitions, premade apps for security tools, organization and sub-organization control, and optional resource sharing with the hosted service at shuffler.io. The last item is the one to read carefully, because it decides whether your install stays entirely inside your own network.

Four cooperating services defined in docker-compose.yml

The deployment is described almost entirely by one file. `docker-compose.yml` starts four services, and the first one is the part that surprises newcomers, because it builds from the local directory rather than pulling a ready image:

services:
  shuffle-security:
    build: .
    image: ghcr.io/shuffle/shuffle-security:latest
    container_name: shuffle-security

That service is the public face and it publishes two ports, with sensible defaults supplied by environment variables:

    ports:
      - "${SHUFFLE_SECURITY_PORT:-3002}:80"
      - "${SHUFFLE_SECURITY_PORT_HTTPS:-3444}:443"

Port 3002 in cleartext and 3444 for TLS means you can bring the stack up on a laptop and decide about certificates later. The compose file sets `BACKEND_HOSTNAME` for the other services and resolves it into `nginx.conf` at container start, which is how requests reach `/api/v1` and `/api/v2` without publishing the backend directly to the network.

The backend is the one service with real state and real privileges:

  backend:
    image: ghcr.io/shuffle/shuffle-backend:latest
    container_name: shuffle-backend
    hostname: ${BACKEND_HOSTNAME}

Two details in that service deserve a second look before you run it anywhere sensitive. It mounts `/var/run/docker.sock`, and it bind-mounts host directories into the container at `/shuffle-apps` and `/shuffle-files`. Mounting the Docker socket grants the container host level control, so a Shuffle deployment inherits the security posture of whatever can talk to that socket. The `.env` file at the repository root is loaded with `env_file: .env`, and you supply it.

Orborus, Worker and where a workflow actually runs

The README's repository map explains the split between the two execution components, and it is short enough to quote without losing anything:

├── backend # Contains backend related code.
│   ├── go-app # The backend golang webserver
│   └── app_sdk # The SDK used for apps
├── functions # Has execution and extension resources, such as the Wazuh integration
│   ├── onprem # Code for onprem solutions
│   │   ├── Orborus # Distributes execution locations
│   │   ├── Worker # Runs a workflow
└ docker-compose.yml # Used for deployments

Orborus distributes execution locations and Worker runs a workflow. That is the whole execution model stated plainly: an orchestration service that knows which execution hosts exist, and a worker that sits on one of them and steps through a run. In the compose file, orborus is a fourth image alongside frontend, backend and the security gateway, so the default install already assumes execution is a separate process from the API.

The `functions/` directory is the part with the longest leash. The README calls it execution and extension resources and names the Wazuh integration as an example, which tells you that distribution-specific glue lives in the platform repository rather than in an app package. If you are adding an integration for a tool your organization runs, the first question is whether it can be expressed as an app with an OpenAPI definition instead.

That question matters because of how apps are built. The README points to an app creator using OpenAPI and to a separate `security-openapis` repository holding the definitions, plus `shuffle-apps` for Python apps. A tool with a clean REST interface becomes an app without writing Python. A tool without one needs a custom app, and the SDK in `backend/app_sdk` is what that work touches.

Apps, the app SDK, and where the split licence bites

The licensing arrangement is unusual enough to be a decision factor rather than a footnote. The README states that all modular information related to Shuffle falls under MIT while Shuffle itself uses AGPLv3, and then enumerates: workflows MIT, documentation MIT, Shuffle backend AGPLv3, and apps, specification and App SDK all MIT.

Read that against the repository layout and the practical consequence is clear. Editing your own workflows, or writing a new app against the MIT-licensed SDK, carries no obligation to publish anything. Modifying the backend does, because the network use clause of AGPLv3 reaches a modified backend running as a service for other people. A security team that wants to change how authentication or the API behaves should get that reviewed before shipping, not after.

The documentation is not in this repository at all. The README states that documentation lives at shuffler.io/docs and is written in the `shuffle-docs` repository, and the same page carries a note asking for sponsorship with the reasoning that it produces more rapid development. That is worth knowing for anyone planning a long deployment: the docs, the apps and the platform move on separate schedules.

The last practical gap in the README is the local development environment. It does not describe the steps, it points at `.github/install-guide.md` with an anchor for the local development installation. The self-hosted path is the same link, so the install guide is the first file to open after the repository overview.

What v2.3.0 actually changed, and what the release notes do not say

v2.3.0 was published on 2026-09-28, the same day as the last push, and its notes are dominated by a single theme: taking AI agents out of the cloud-only box. According to the release notes, AI Agents can run on your own servers and in hybrid setups, pick the backend address and tool timeouts appropriate to the environment, and recover results that arrive late. On self-hosted installs they can use local credentials or Shuffle AI synced from the cloud.

Two smaller items from the same release are worth noting because they describe behaviour rather than features. Workflow runs started by an agent receive extra checks and permission checks, and in hybrid setups the worker stops cleanly when an agent action takes over, so runs do not hang or repeat work. The note adds that this now only happens in the cases where it should, which reads as a correction of an earlier over-broad behaviour rather than a new capability. Trigger reliability and handling of provider rate limits are also listed.

What the release notes do not say is as informative as what they do. There is no migration note, no breaking change list, and no upgrade procedure. The two preceding tags, v2.3.0-rc1 and v2.3.0-rc2, show a project shipping release candidates through pull requests in the days before the final tag, which is normal, but it also means the diff between v2.2.1 and v2.3.0 is broad. With 493 open issues on the repository, planning an upgrade window matters more than usual.

The comparison to make is not against another open source SOAR so much as against the commercial alternative. A paid orchestration platform gives you a vendor support contract and a defined upgrade path; Shuffle gives you source code, an OpenAPI app model and the freedom to change the backend under AGPL terms. Teams that lack the people to maintain either side of that trade are the ones most likely to regret the choice.

Editorial conclusion

Shuffle fits a security team that has outgrown copy and paste alert triage but does not want a commercial SOAR agreement, and it fits service providers who need one platform to hand to several clients. The cost is assembly work: four images, an `.env` file, a database service and a set of app definitions that live in separate repositories. Before adopting, read the install guide at `.github/install-guide.md`, decide whether the hybrid resource sharing with shuffler.io stays disabled, and check the licence line for the component you intend to modify, because the backend is AGPLv3 while workflows and apps are MIT. The repository is not archived and the last push was on 2026-09-28, which is the same day v2.3.0 shipped.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. Shuffle/Shuffle on GitHub