Horsies
PostgreSQL-backed background task queue and workflow engine for Python.
Most businesses need durable, observable systems with strong execution guarantees. Traditional queues do not give you that out of the box. You end up writing tedious state machines around them, and your execution state gets mixed into your business logic, because your execution layer was never durable.
Horsies lets you declare your conditional business logic as tasks and workflows, without managing execution state on top of it.
Using Rust? The Rust docs cover the horsies crate. The Python and Rust libraries have almost the same API and mental model, but they are not interoperable.
What you get
Section titled “What you get”The signature is the contract
The function signature is the contract, and every value is held to it for its whole life. A wrong value is refused when you send it, before anything is stored.
One way to fail
Every task returns its value or a TaskError with a code. Retries follow those codes, so you decide which failures are worth another attempt.
No unclear state
Nothing lives in memory. Work is claimed and leased with an identity, so even a crash is traceable: you can see which worker held the task, when, and what happened to it.
A process per task
By default, each running task has a child process to itself, so a segfault, an out-of-memory kill or a timeout ends that task and no other.
Workflows
A workflow is a graph of tasks: each node says what it waits for and what happens if that fails, and the workflow says what counts as success. A whole workflow can be one node in another.
Monitoring comes with it
The web UI reads the same records your workers write, so there is no agent or exporter to set up. You get the live state and the history of your tasks, queues, workflows, schedules and workers.
No invalid boot
You cannot boot an invalid configuration. horsies check runs the same validation in CI, with no worker and no database.
Many schedulers, one fire
Run as many schedulers as you want for high availability, without worrying about double fires.
The web UI
Section titled “The web UI”









Quick Example
Section titled “Quick Example”from pydantic import SecretStrfrom horsies import Horsies, AppConfig, PostgresConfig, TaskResult, TaskError, Ok, Err
app = Horsies(AppConfig( broker=PostgresConfig( database_url=SecretStr("postgresql+psycopg://user:pass@localhost:5432/mydb"), ),))
@app.task("add_numbers")def add_numbers(*, a: int, b: int) -> TaskResult[int, TaskError]: return TaskResult(ok=a + b)
# Send and get resultmatch add_numbers.send(a=5, b=3): case Ok(handle): result = handle.get() if result.is_ok(): print(result.ok_value) # 8 case Err(send_err): print(f"Send failed: {send_err.code} - {send_err.message}")For AI agents
Section titled “For AI agents”llms.txt lists every page of these docs with keywords. The package ships a skill folder for coding agents; copy it with horsies skills install --target DIR.
