Process Compose: a non-containerized process orchestrator in a single Go binary

The problem Process Compose solves, and who it is for

The README states the motivation plainly: sometimes you do not want to deal with docker files, volume definitions, networks and docker registries. That is the whole pitch. If your services are already binaries or shell commands on the machine, wrapping each one in an image adds a build step, a registry, a network namespace and a volume mapping before the process even starts. Process Compose skips all of that and runs the commands directly.

The audience is developers and operators who run several related processes on one machine and want ordering, restarts and log aggregation without a container runtime. Typical shapes: a backend, a worker and a database started together for local development; a test harness that needs a service up before the test command runs; a set of daemons on a single host. Because it is written in Go, the README says it is a single binary file with no other dependencies, which matters on machines where installing a container runtime is not an option.

It is not a general-purpose cluster scheduler. Everything in the README describes one host, one project directory and one YAML file.

How process-compose.yaml turns into a running process tree

The unit of configuration is a YAML file named process-compose.yaml. Each entry under processes has a command, and dependencies are expressed with depends_on plus a condition. The README's own example uses condition: process_completed, which means the dependent process waits until the named process finishes successfully rather than merely starting. That distinction is the core of the scheduler: a condition gates the edge, not just the presence of the key.

Around that graph, the README lists the surrounding machinery: process recovery policies, health checks for liveness and readiness, per-process or global environment variables rendered through envsubst, per-process or single-file logs, and log caching. Scheduled processes use cron and interval triggers. File watching restarts a process when its files change, optionally cascading to dependents. Namespaces group processes so they can be started, stopped and restarted together from the CLI or the TUI.

The same binary acts as both server and client. The README describes a REST API with OpenAPI documentation and optional token authentication through PC_API_TOKEN, a Terminal User Interface, and an MCP server that exposes processes as tools and resources to AI assistants, optionally including the project's own control plane for start, stop, scale, list and logs. The go.mod file backs this up: gin for the HTTP layer, tview and tcell for the TUI, gocron for scheduling, fsnotify for file watching, mark3labs/mcp-go for the MCP server. The repository also contains a Cargo workspace with crates/client and crates/example, so a Rust client exists alongside the Go implementation.

Install and a first working process-compose.yaml

The README does not inline installation commands. It points at an installation page and a Quick Start page, and the related searches include brew, nix, flake and devbox, which suggests those are the channels people look for. Check the installation page for your platform rather than guessing a package name. The repository does carry a default.nix and a flake.nix, and the Makefile has build-nix and nix-update-hash targets, so a Nix build path is present in the tree; the Makefile also builds with CGO_ENABLED=0 go build, which is how the single static binary is produced.

Once the binary is on your PATH, a minimal config looks like the README example. Write this to process-compose.yaml:

version: "0.5"

processes:
  hello:
    command: echo 'Hello World'
  pc:
    command: echo 'From Process Compose'
    depends_on:
      hello:
        condition: process_completed

The pc process does not start until hello has completed, so the ordering is enforced by the scheduler, not by shell chaining. Start it from the directory containing the file:

process-compose

The README says this launches the workflow; with no flags you get the TUI, which shows process state and lets you restart processes manually. If you want to drive it from another terminal or a script, the REST API is the documented path, and PC_API_TOKEN is the environment variable named for token authentication. The README does not document the default port, so read the API documentation before pointing a client at it. For log handling, the README lists per-process logs and a global single-file mode plus log caching; the exact keys live in the launcher documentation, not in the README.

Where Process Compose is the wrong tool

There is no isolation. The README's own framing is that it manages non-containerized applications, and the commands run on the host. If two services need different library versions, conflicting ports or different users, Process Compose will not separate them the way a container runtime does. Nothing in the README mentions cgroups, namespaces, seccomp or resource limits, so do not expect them.

Portability of the runtime environment is also absent. A process-compose.yaml assumes the commands exist on the machine. Docker Compose, by contrast, ships the environment inside an image, which is why a Compose file can move between machines and a process-compose.yaml often cannot without provisioning steps.

The README does not document rollback. There is a feature for on-the-fly project update and on-the-fly process configuration edit, but no described mechanism for reverting a project to a previous state, so treat configuration changes as you would any other file edit and keep them in version control yourself.

Finally, this is a single-host tool. The README describes namespaces, replicas and scheduling, all of which are about processes on one machine. If you need placement across a fleet, this is not the layer for it.

Process Compose versus Docker Compose and overmind

Docker Compose and Process Compose share a YAML-and-dependencies shape, which is why people search for the comparison. The difference is the execution substrate. Docker Compose builds and runs images in containers, so the service definition includes the environment, and volume and network definitions are part of the model. Process Compose runs commands on the host, so the environment is whatever the machine already has. The README's stated reason for existing is exactly this trade: no docker files, no volume definitions, no networks, no registries. You give up reproducibility and isolation; you gain a single binary and no daemon.

Overmind is the closer comparison, since it also supervises local processes with a Procfile-style config and a terminal UI. The README does not mention Overmind, so the honest statement is that the overlap is in the category, not in the documented feature set. What the README does document for Process Compose is a wider surface than process supervision alone: a REST API with OpenAPI docs, an MCP server for AI assistants, cron and interval scheduling, file watching with cascade restarts, namespaces with group start and stop, replicas, dependency graph visualization, and merge configuration files. If you only need to run a Procfile and tail output, that surface is more than you asked for.

A third option worth naming is systemd, which also supervises local processes. Process Compose differs in being project-scoped and user-facing: it reads a file in your working directory and gives you a TUI and an API, rather than registering units with the init system.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-21, one week before this writing. Releases are frequent: v1.122.0 on 2026-08-17, v1.120.0 on 2026-07-11, v1.116.0 on 2026-06-16. That cadence means upgrades arrive often, and the practical cost is reading release notes before bumping, especially if you depend on the REST API or the MCP server, both of which are recent additions and therefore the most likely to shift.

The project is Apache-2.0. For most users that is a permissive licence with a patent grant and a requirement to preserve notices; the LICENSE file is in the repository root. If you embed the binary in a product or modify it, read the licence text and your own legal counsel rather than treating this paragraph as advice.

The Makefile embeds version metadata at build time through -ldflags, including CheckForUpdates=true, so a self-built binary is wired to check for updates. If you build from source for a locked-down environment, note that flag and the Version, Commit and Date variables it sets.

One governance detail worth knowing: the README says English is not the maintainer's native language and invites pull requests correcting grammar or spelling. That is a statement about the project's contributor culture, and it also means documentation wording may lag the code.

Editorial conclusion

Adopt Process Compose when your services are already local binaries or scripts and a Dockerfile, volume and network setup is pure overhead: write process-compose.yaml, run process-compose, and use the TUI or REST API to control it. Do not adopt it when you need process isolation, cgroup limits, image portability or multi-host scheduling, because it runs commands directly on the host and nothing in the README claims otherwise. Before committing, verify the install path for your platform on the installation page, confirm whether your config needs the version: "0.5" key, and decide how you will supply PC_API_TOKEN if you expose the REST API beyond localhost.

Frequently asked questions

Official sources

1. F1bonacc1/process-compose on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases