Quick Start

Zizq is incredibly simple to get up and running. The server is a static binary and needs no configuration out of the box.

Tip

Read the Command Line Reference for full details on the zizq command.

🔧 Set up the server instance

You run once instance of the server and connect many clients to it. The server does almost all of the work.

1. Download the binary.

Download:

curl -sLO https://github.com/zizq-labs/zizq/releases/download/v0.7.3/zizq-0.7.3-linux-x86_64.tar.gz

2. Extract it.

Extract:

tar -xvzf zizq-0.7.3-linux-x86_64.tar.gz

3. Run it to start the server.

Run:

./zizq serve

Zizq 0.7.3
2026-04-05T05:41:26.893318Z  INFO zizq::commands::serve: no license key provided, running in free tier
2026-04-05T05:41:27.081150Z  INFO zizq::commands::serve: store opened root_dir=./zizq-root
2026-04-05T05:41:27.081547Z  INFO zizq::commands::serve: admin API listening addr=127.0.0.1:8901 scheme=http
2026-04-05T05:41:27.081842Z  INFO zizq::commands::serve: in-memory indexes rebuilt ready=0 scheduled=0
2026-04-05T05:41:27.081890Z  INFO zizq::commands::serve: primary API listening addr=127.0.0.1:7890 scheme=http
Listening on http://127.0.0.1:8901 (admin)
Listening on http://127.0.0.1:7890 (primary)

Or, run it with Docker

Instead of downloading the binary, you can run the published image, available for linux/amd64 and linux/arm64 on Docker Hub and as ghcr.io/zizq-labs/zizq. However you run Zizq, the rest of this quick start guide remains the same.

Run:

docker run -d --name zizq -p 7890:7890 -v zizq-data:/var/lib/zizq zizqlabs/zizq:0.7.3

Queue data is stored in /var/lib/zizq, so mount a volume there or it is lost with the container. The admin API stays private to the container, so run zizq top inside it.

Run:

docker exec -it zizq zizq top

The default image contains only the zizq binary. Use the -alpine tag (e.g. zizqlabs/zizq:0.7.3-alpine) for a shell, curl and jq inside the container. The server is configured with the same ZIZQ_* environment variables described in the Command Line Reference.

⚙️ Enqueue and process your first job

Tip

Detailed documents on the HTTP API for enqueueing and processing jobs are available in the HTTP API Reference.

With the server running, we can already use it to enqueue jobs and simulate processing those jobs without the use of a client library. This example uses curl (and a small amount of jq to help with the JSON) in bash, and serves purely to illustrate the flexibility of Zizq.

Note

This is a novel example. In reality applications will use a client library or will integrate with the HTTP API programatically.

1. Enqueue a job

Request:

curl -XPOST \
  http://localhost:7890/jobs \
  -s \
  -H 'Content-Type: application/json' \
  -d '{
    "queue":"example",
    "type":"hello_world",
    "payload":{"greet":"Universe"}
  }' | jq

Response:

{
  "id": "03g04auga7wsnux60e4r7wip1",
  "type": "hello_world",
  "queue": "example",
  "priority": 32768,
  "status": "ready",
  "ready_at": 1777005093930,
  "attempts": 0,
  "duplicate": false
}

2. Process the job

Note

This script does not exit until it is interrupted. The while loop receives lines of JSON from the server. Blank lines are heartbeats and are skipped.

Script:

curl -XGET \
  "http://localhost:7890/jobs/take" \
  -sN | while IFS= read -r job; do
    [[ "$job" = "" ]] && continue

    id="$(echo "$job" | jq -r ".id")"
    type="$(echo "$job" | jq -r ".type")"

    echo "Processing job with id=${id} type=${type}..."
    echo "$job" | jq

    echo "Acknowledging completion..."
    curl -XPOST -s "http://localhost:7890/jobs/${id}/success"

    echo "Done."
  done

Output:

Processing job with id=03g04auga7wsnux60e4r7wip1 type=hello_world...
{
  "id": "03g04auga7wsnux60e4r7wip1",
  "type": "hello_world",
  "queue": "example",
  "priority": 32768,
  "status": "in_flight",
  "payload": {
    "greet": "Universe"
  },
  "ready_at": 1777005093930,
  "attempts": 0,
  "dequeued_at": 1777005818220
}
Acknowledging completion...
Done.

3. Keep going

Try enqueueing more jobs while that little bash script worker is still running. Does the worker pick those up?

What happens if you comment out the acknowledgement (/jobs/${id}/success) line in the worker script?

🔌 Integrate with your application

Note

Read the specific documentation for official clients, and the full Zizq HTTP API Reference for the API.

Clients —and consequently workers— can be written in any programming language. Any number of clients can connect to the server (subject to operating system limits).

You can:

1. Add an official client library to your application
2. Integrate with the HTTP API directly

🎉 Congratulations, you’re all set to go!