Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Install Orloj

This guide covers how to install Orloj for local evaluation and production-like use: from source (clone and run or build), from release binaries (GitHub Releases), or from container images (GitHub Container Registry). Use release artifacts when you want a tagged, published build instead of building from source.

Before You Begin

  • From source: Go 1.24+, optionally Bun 1.3+ for docs/frontend
  • Containers: Docker
  • API checks: curl and jq

From source

Clone the repo, then either run in place or build binaries.

git clone https://github.com/OrlojHQ/orloj.git && cd orloj

Run from source (no build)

Single process with embedded worker:

go run ./cmd/orlojd \
  --storage-backend=memory \
  --task-execution-mode=sequential \
  --embedded-worker \
  --model-gateway-provider=mock

Build local binaries

go build -o ./bin/orlojd ./cmd/orlojd
go build -o ./bin/orlojworker ./cmd/orlojworker
go build -o ./bin/orlojctl ./cmd/orlojctl

Run the server:

./bin/orlojd --storage-backend=memory --task-execution-mode=sequential --embedded-worker --model-gateway-provider=mock

From release binaries (GitHub Releases)

Download the server, worker, and CLI for your platform from GitHub Releases. Artifacts are named by binary, git tag, OS, and arch (e.g. orlojd_v0.1.0_linux_amd64.tar.gz, orlojctl_v0.1.0_darwin_arm64.tar.gz). Verify with checksums.txt on the same release. Extract and run:

# Example: after downloading and extracting orlojd, orlojworker, orlojctl for your OS/arch
./orlojd --storage-backend=memory --task-execution-mode=sequential --embedded-worker --model-gateway-provider=mock

Use a specific version tag (e.g. v0.1.0) for production.

CLI only for hosted deployments

If orlojd and workers run elsewhere—Docker Compose on a VPS, Kubernetes, GHCR images, or a managed host—you do not need the full repo on your laptop. Download only the orlojctl_*_<os>_<arch> archive for your platform from the same GitHub Releases page, verify it with checksums.txt, extract the binary, and put it on your PATH (or run it by full path). Container images ship the server and worker binaries only, not the CLI.

Point orlojctl at your API with --server and authenticate with a bearer token; see Remote CLI and API access. Prefer a CLI version that matches your server’s release tag when possible.

From container images (GHCR)

Published releases are pushed to GitHub Container Registry. Pull and run the server and worker without building from source:

docker pull ghcr.io/orlojhq/orloj-orlojd:latest
docker pull ghcr.io/orlojhq/orloj-orlojworker:latest

Use a version tag instead of latest for production (e.g. ghcr.io/orlojhq/orloj-orlojd:v0.1.0). You still need Postgres and optionally NATS for persistence and message-driven mode; see Deployment for full-stack options. Example, server only with in-memory storage:

docker run --rm -p 8080:8080 ghcr.io/orlojhq/orloj-orlojd:latest \
  --addr=:8080 \
  --storage-backend=memory \
  --task-execution-mode=sequential \
  --embedded-worker \
  --model-gateway-provider=mock

For a full stack (Postgres, NATS, server, workers), use the VPS or Kubernetes deployment guides with image: ghcr.io/orlojhq/orloj-orlojd:<tag> (and the worker image) instead of building from the repo.

Docker Compose (from source)

To run the full stack from the repo (Postgres, NATS, orlojd, two workers) with a local build:

git clone https://github.com/OrlojHQ/orloj.git && cd orloj
docker compose up --build

This builds the server and worker images from the Dockerfile. To use release images instead, override the service images to ghcr.io/orlojhq/orloj-orlojd:<tag> and ghcr.io/orlojhq/orloj-orlojworker:<tag> (see Deployment).

Verify Installation

curl -s http://127.0.0.1:8080/healthz | jq .
go run ./cmd/orlojctl get workers

Expected result:

  • healthz returns healthy status.
  • At least one worker is Ready.

Next Steps