guide · installation

Install for your runtime.

The free bunqueue server runs on Bun. Your application uses the client for its own language. Bun applications can also embed the queue directly. The server, clients and queue features are included under MIT.

Requirements

• The bunqueue server and embedded runtime require Bun v1.4.0 or later when run from the package. Standalone executables and Docker images already include the runtime.
• External Node.js, Deno, Python, PHP, Go, Rust, and Elixir clients need their SDK’s documented runtime plus a reachable Bun-powered bunqueue server; they do not require Bun in the client process.

Install

Bun

bun add bunqueue

That is it. The package includes the client library, standalone server, and CLI. msgpackr is its only direct runtime dependency; SQLite, PostgreSQL connectivity, cron parsing, HTTP, WebSocket, and S3 use Bun’s native APIs.

Node.js / Deno

npm install bunqueue-client    # Node.js 20+
deno add npm:bunqueue-client   # Deno 2+

Python

pip install bunqueue-client

PHP

composer require bunqueue/client

Go

go get github.com/egeominotti/bunqueue/sdk/go

Rust

cargo add bunqueue-client

Elixir

# Hex release upcoming; use sdk/elixir as a path dependency today
{:bunqueue_client, path: "../bunqueue/sdk/elixir"}

The Bun bunqueue package bundles the client, the server, and the CLI. Every other SDK is a client only: it connects to a bunqueue server, started once with bunx bunqueue start (see SDKs and Server Mode).

Verify it works

Bun

Save this as test.ts and run bun run test.ts:

import { Queue, Worker } from 'bunqueue/client';

// Both Queue and Worker must have embedded: true
const queue = new Queue('test', { embedded: true });
const worker = new Worker(
  'test',
  async (job) => {
    console.log('Processing:', job.data);
    return { success: true };
  },
  { embedded: true }
);

await queue.add('hello', { message: 'bunqueue is working!' });

Node.js / Deno

Start a server (bunx bunqueue start), save this as test.ts, then run node --experimental-strip-types test.ts (Node 22+) or deno run -A test.ts:

import { Queue, Worker } from 'bunqueue-client';

// Both Queue and Worker must have embedded: false
const queue = new Queue('test', { embedded: false });
const worker = new Worker(
  'test',
  async (job) => {
    console.log('Processing:', job.data);
    return { success: true };
  },
  { embedded: false }
);

await queue.add('hello', { message: 'bunqueue is working!' });

Python

Start a server (bunx bunqueue start), then run python test.py:

from bunqueue import Queue, Worker

queue = Queue("test")  # connects to localhost:6789
queue.add("hello", {"message": "bunqueue is working!"})

def process(job):
    print("Processing:", job.data)
    return {"success": True}

Worker("test", process).run()

PHP

Start a server (bunx bunqueue start), then run php test.php:

use Bunqueue\Queue;
use Bunqueue\Worker;

$queue = new Queue('test'); // connects to localhost:6789
$queue->add('hello', ['message' => 'bunqueue is working!']);

$worker = new Worker('test', function (Bunqueue\Job $job) {
    var_dump($job->data());
    return ['success' => true];
});
$worker->run();

Go

Start a server (bunx bunqueue start), then go run .:

queue := bunqueue.NewQueue("test", bunqueue.Options{}) // localhost:6789
defer queue.Close()
queue.Add("hello", map[string]any{"message": "bunqueue is working!"}, nil)

worker := bunqueue.NewWorker("test", func(job *bunqueue.Job) (any, error) {
    fmt.Println("Processing:", job.Data())
    return map[string]any{"success": true}, nil
}, bunqueue.WorkerOptions{})
worker.Run()

Rust

Start a server (bunx bunqueue start), then cargo run:

use bunqueue_client::{ConnectionOptions, JobOptions, Queue, Value, Worker, WorkerOptions};

let queue = Queue::new("test", ConnectionOptions::default()); // localhost:6789
let data = Value::Map(vec![(Value::from("message"), Value::from("bunqueue is working!"))]);
queue.add("hello", data, JobOptions::default())?;

let worker = Worker::new("test", |job| {
    println!("Processing: {:?}", job.data());
    Ok(Value::from(true))
}, WorkerOptions::default());
worker.run()?;

Elixir

Start a server (bunx bunqueue start), then mix run test.exs:

queue = Bunqueue.queue("test")  # connects to localhost:6789
{:ok, _job} = Bunqueue.Queue.add(queue, "hello", %{message: "bunqueue is working!"})

worker =
  Bunqueue.Worker.new("test", fn job ->
    IO.inspect(job.data, label: "Processing")
    {:ok, %{success: true}}
  end)

Bunqueue.Worker.run(worker)

You should see Processing: { message: "bunqueue is working!" }. Next: the Quick Start builds on this.

To check the server and CLI:

bunqueue --version
bunqueue start

Docker (runtime included)

From 2.9.5, release images are available on Docker Hub as egeominotti/bunqueue and on GHCR as ghcr.io/egeominotti/bunqueue. Both provide Linux amd64 and arm64 images under the same tag; Docker selects the appropriate architecture.

docker run -d --name bunqueue \
  -p 6789:6789 -p 6790:6790 \
  -v bunqueue-data:/app/data \
  egeominotti/bunqueue:2.9.5

curl http://localhost:6790/health

The named volume persists SQLite data at /app/data. TCP clients connect to port 6789; HTTP endpoints use port 6790. Use a version tag or digest for deployments; latest follows the most recently published release.

Single binary (no Bun required)

Each release ships self-contained executables, useful on servers and edge devices (Raspberry Pi, ARM64 boxes) where you don’t want to install a runtime:

Starting with 2.9.5, choose one of eight archives from GitHub releases:

Operating system	Architecture	Archive
Linux (glibc)	x64	bunqueue-linux-x64.tar.gz
Linux (glibc)	arm64	bunqueue-linux-arm64.tar.gz
Linux (musl / Alpine)	x64	bunqueue-linux-x64-musl.tar.gz
Linux (musl / Alpine)	arm64	bunqueue-linux-arm64-musl.tar.gz
macOS	x64 / Intel	bunqueue-darwin-x64.tar.gz
macOS	arm64 / Apple Silicon	bunqueue-darwin-arm64.tar.gz
Windows	x64	bunqueue-windows-x64.zip
Windows	arm64	bunqueue-windows-arm64.zip

For example, on Linux arm64 with glibc:

curl -fsSLO https://github.com/egeominotti/bunqueue/releases/latest/download/bunqueue-linux-arm64.tar.gz
tar -xzf bunqueue-linux-arm64.tar.gz
sudo mv bunqueue-linux-arm64 /usr/local/bin/bunqueue

bunqueue start --data-path /var/lib/bunqueue/queue.db

A SHA256SUMS file is attached to every release for checksum verification. Download it from the same release as your archive. On Windows, extract the ZIP and run bunqueue-windows-x64.exe or bunqueue-windows-arm64.exe.

The binary is the full server + CLI. For the client SDK in your app code you still install the package (bun add bunqueue).

Install from source

git clone https://github.com/egeominotti/bunqueue.git
cd bunqueue
bun install
bun run build

TypeScript support

bunqueue is written in TypeScript and ships full type definitions:

import type {
  Job,
  JobOptions,
  WorkerOptions,
  StallConfig,
  DlqConfig,
  DlqEntry,
} from 'bunqueue/client';

Next Steps

• Quick Start, build your first queue
• Introduction, what bunqueue is and when to use it
• MCP Server, let AI agents manage your queues