Installation

npm install -g @oren-sh/cli

Prerequisites

Node 22 or newer and Docker.

That is all. Oren runs every worker in a container, so Docker is required — but Dagger, the engine underneath, does not need to be installed: its CLI is downloaded automatically on first run, in the exact version Oren expects.

Checking

oren doctor

prerequisites
  ✓ Node                   v22.21.1
  ✓ Docker                 Docker version 29.1.2
  ✓ Engine CLI             cached (~/.cache/dagger)
  ! Execution engine       stopped — starts by itself on the next run
✓ everything ready for oren run

If Docker is missing, doctor says what to do and exits with code 1 — useful to check in a CI before running the pipeline.

Language

The CLI speaks English by default, and Portuguese when the environment asks. The choice comes, in this order, from OREN_LANG, LC_ALL, LC_MESSAGES and LANG; a language with no catalogue falls back to English.

OREN_LANG=pt oren run dev

The chosen language travels in the Accept-Language of every request to the portal, so that the server’s error message arrives in the same language as the screen — rather than one sentence per language in the same terminal.

The published catalogue

The default is https://oren.sh, and it needs no configuration: oren add techlite/build-docker-image resolves on a clean machine.

To point somewhere else — your own, if you self-host:

export OREN_REGISTRY=https://your-portal

Or record it in the project, which is what gets committed when a team shares the same catalogue:

.oren/config.json

{ "registry": "https://your-portal" }

The variable belongs to the ENVIRONMENT and the file to the PROJECT — and that difference is what decides between them: the file is committed, so the whole team resolves from the same portal without each person configuring their own. The variable overrides it, and exists for the individual case.

oren.lock does not record where it came from, only what was resolved — so two teams pointing at different mirrors produce the same lock for the same content.

None of this is needed for tasks coming from a directory in your own repository — see The portal.

The execution engine

On first run, Oren starts a container of its own (oren-engine-<version>) with its own cache volume. It is the official Dagger image — not a fork.

Having its own means clearing Oren’s cache does not affect any other use of Dagger on your machine:

oren cache             # space used and ceiling
oren cache prune       # free the unused
oren cache limit 20GB  # cap the growth
oren cache clear       # remove the engine and the whole cache

Setting a ceiling is worth it: by default the engine can grow to a large fraction of the free disk.