Pages on ukue.com

About

Mon, 01 Jan 0001 00:00:00 +0000

ukue.com is the home of ukue, read µkue, a micro queue: a job queue that lives in one file. It keeps background jobs, their retries, their start times and the jobs that failed for good in a single SQLite file. A program can embed it as a library, or run the one small ukue binary when other programs, in any language, need the same queue.

Why It Exists

Most apps reach the point where some work has to happen later, or somewhere other than the web request: a welcome email, a resized photo, a webhook that must get through even if the other side is down for an hour. The usual answer is a queue server such as Redis or RabbitMQ. For a small team that’s one more service to install, secure, watch, back up and pay for, sometimes only to send a few emails. ukue does the same job with nothing running beside the app.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

ukue.com would like to hear from:

Anyone trying ukue out. What worked, what got in the way, and what you used before.
Anyone who found a bug. A job that ran when it shouldn’t have, one that didn’t run, an error you didn’t expect.
Anyone with an idea for something ukue should do, or a language it should have an example for.

Write to info@ukue.com.

Bug reports are also welcome on GitHub. It helps to include what ukue version prints, your operating system, and the steps that show the problem. Please don’t send real customer data: a few made-up jobs that show the same thing are enough.

Download ukue

Mon, 01 Jan 0001 00:00:00 +0000

The ukue command is one file with nothing else to install. Each archive below holds it with its license files. The links always point to the latest release.

System	Download
Linux, x86-64	ukue_linux_amd64.tar.gz
Linux, ARM64	ukue_linux_arm64.tar.gz
macOS, Apple silicon	ukue_darwin_arm64.tar.gz
macOS, Intel	ukue_darwin_amd64.tar.gz
Windows, x86-64	ukue_windows_amd64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Install

On Linux or macOS:

tar -xzf ukue_linux_amd64.tar.gz
sudo mv ukue /usr/local/bin/
ukue version

The Linux binaries are static, so they run on any distribution. The macOS binaries aren’t signed by Apple, so macOS may block the first run; allow it in System Settings under Privacy & Security, or run xattr -d com.apple.quarantine ukue. On Windows, unzip the archive and put ukue.exe in a folder on your PATH.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

ukue is a job queue that lives in one file. This page takes you from nothing to jobs running in a few minutes, from the command line, from Go, and from any other language.

1. Get the ukue Command

Download the archive for your system from the download page, unpack it and put ukue somewhere on your PATH. Check it works:

ukue version

Go programmers who only want the library can skip this and go to step 4.

The ukue File Format

Mon, 01 Jan 0001 00:00:00 +0000

A ukue file is an SQLite database with two tables in it. Any program that can write SQLite can add jobs to it, and a program that follows the steps on this page can claim and finish them too, alongside the ukue command and the Go package. This is version 1 of the format. The complete description, with every SQL statement, is FORMAT.md on GitHub.

What stays the same. The version is stored in the file. Within version 1, later releases may add indexes, settings and columns with default values, but nothing is removed or renamed, and no column changes meaning. A change that older programs couldn’t handle safely gets a new version number, and ukue refuses to open a file whose version it doesn’t know.

The ukue HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

ukue serve puts a ukue file behind a small JSON API, so programs in any language, and on other machines, can add and run jobs. Go programs can mount the same API in their own HTTP server with the server package.

ukue serve jobs.ukue                              # listens on 127.0.0.1:7660
UKUE_TOKEN=s3cret ukue serve --addr :7660 jobs.ukue

The Basics

JSON in and out. Errors come back as {"error": "..."} with a 4xx or 5xx status.
Token. When the server has a token, from UKUE_TOKEN or --token-file, every request except /v1/health must send Authorization: Bearer <token>. The server won’t listen beyond your own machine without a token, unless you start it with --allow-no-token.
Durations can be a number of seconds, such as 30 or 0.5, or a string such as "90s" or "1h30m".
Times in answers are in UTC, such as "2026-10-06T09:00:00.000Z".
Payloads. A payload that is a JSON string is stored as its text, and any other JSON value is stored as compact JSON. Send binary data as payload_base64. Answers give the payload back as text when it is valid UTF-8, and as payload_base64 otherwise.
Size. A request may be up to 1 MiB, unless the server was started with a different --max-body.
Browsers. Requests that change something are refused when they come from a web page on another site. Without a token, the server also answers only requests addressed to localhost, 127.0.0.1 or ::1, so a web page can’t reach it through a DNS name that points at your machine.

Add a Job

POST /v1/jobs