Installation notes
Revetly 0.8.0 — engine image revetly:0.8.0
--------------------------------------------------------------------
Revetly is product memory for a project: the stories you agreed to, the
decisions behind them and what actually shipped, kept as markdown in your own
git repo and read into a graph an AI agent queries before it writes anything.
It runs entirely in Docker on your machine. There is no registry and no
account: the tarball in this folder IS the product, and the engine scaffolds
its own instance once you load it.
WHAT YOU NEED FIRST
--------------------------------------------------------------------
* Docker, with Compose v2 (`docker compose version` should answer).
* An internet connection for the first start. The graph database
(neo4j:5.26) is pulled from Docker Hub — deliberately not bundled here,
because it is a stock image you can get without us. The same goes for the
authorization server, if you ask `--issuer-kit` for one: that is a stack of
its own, outside this instance, and an instance you reach over stdio or
loopback needs neither it nor a login. Point `[auth]` at an issuer you
already have and nothing is pulled at all.
* An LLM provider API key of your own, and the willingness to spend on it.
Revetly never ships a model or a key: reading your files into the graph
calls your provider on your account. Nothing is billed until you run
`ingest`, and two commands price it before you do. A full instance needs
that key; a lite instance declares `[llm] provider = "none"` and
`[embedding] provider = "none"` and needs none — add `--lite` to the
`revetly init` line below and the scaffold declares it for you.
* A Claude client that can put a draft in front of you, because approving one
is something the MCP server raises in your session and you answer. Either
works: the TERMINAL CLI at version 2.1.76 or newer, which renders the
review as a dialog, or the desktop app, which renders it as a panel in the
chat with Approve and Reject. A client that can do neither installs and
connects fine and never writes anything you draft — the engine says so
rather than reporting a rejection you never made.
WHICH FILE IS YOURS
--------------------------------------------------------------------
A Docker image tarball holds one architecture. Run `uname -m` on the machine
that will RUN the container — a server, if that is where this is going, not
the laptop you are downloading on:
x86_64 / amd64 -> 0.8.0/revetly-engine-0.8.0-linux-amd64.tar.gz
arm64 / aarch64 -> 0.8.0/revetly-engine-0.8.0-linux-arm64.tar.gz
VERIFY WHAT YOU DOWNLOADED
--------------------------------------------------------------------
SHA256SUMS holds the digests. From the 0.8.0/ folder:
sha256sum -c SHA256SUMS # Linux
shasum -a 256 -c SHA256SUMS # macOS
Checking reports the tarball you did not download as missing, and exits
non-zero for it. That is expected — you only need your own line to say OK.
030dc9fed788307f6e8badccb5bbc850e364e1b4f8f80bf18658af3a7fa28f7d revetly-engine-0.8.0-linux-amd64.tar.gz
1ac32e4799508813f8a6962cc8b0ff90b867f1439729aa8dab384df9a7fee73b revetly-engine-0.8.0-linux-arm64.tar.gz
INSTALL
--------------------------------------------------------------------
Three commands. The second is your own project directory: an empty folder for
a fresh instance, or the repo you are adopting Revetly into (nothing of yours
is overwritten — existing files are kept and reported as kept).
docker load < 0.8.0/revetly-engine-0.8.0-linux-amd64.tar.gz
cd /path/to/your/project
docker run --rm -v "$PWD:/project" -u "$(id -u):$(id -g)" \
revetly:0.8.0 revetly init --transport container --group-id your-product
-u "$(id -u):$(id -g)" runs the engine as you. Leave it out on Linux and
the files it writes are owned by root, in your own project directory.
--lite, added to that line, declares no provider on both sinks: no key to
paste, nothing billed, keyword search and the deterministic links only.
`revetly manual show howto/run-without-a-provider` is the guide.
--group-id names this instance's graph namespace, and is required here:
inside the engine your directory is mounted as /project, so its own name
would be the same for every recipient. Use your product's name.
`init` writes the instance and prints what to do next. It leaves a compose
file, a .mcp.json, a revetly.toml, an .env, a README of its own and
CLAUDE.md — the working agreement the AI agent working in that folder
reads — then commits them to git.
FIRST RUN
--------------------------------------------------------------------
docker compose up -d
docker compose exec revetly revetly doctor
`doctor` checks the whole chain and names the fix for anything it finds; it
bills nothing. Expect exactly one failure on a fresh instance that declares a
provider. `init` writes the key line in .env empty rather than filling it with
a fake value, so what doctor prints is:
[FAIL] provider key OPENAI_API_KEY is not set
-> add it to .env at the project root, or inject it
as a secret
Paste your own key on that line and run `doctor` again. An instance declaring
`[llm] provider = "none"` and `[embedding] provider = "none"` reads no key at
all, so it never prints that line.
From there, two pages take over. The tutorial in this release's manual is one
path with no choices, from here to a search that answers:
docker compose exec revetly revetly manual show first-hour
And the README that `init` wrote in your own directory covers the loop —
drafting, the approval dialog, shipping with a verdict per criterion — and the
two commands that say what an ingest will read — and, where a provider is
declared, what it costs — before you run it.
THE MANUAL
--------------------------------------------------------------------
This release's manual is in 0.8.0/manual/, here in this folder: the
how-to guides, one goal to a page in numbered steps, and the pages that
explain the parts you are invited to extend — the connector contract, writing
a connector or a write adapter, driving the engine from your own client, what
a failed pass and a stale corpus mean, and every runtime input the engine
reads. They describe THIS release and no other.
Open 0.8.0/manual/index.html in a browser to read the whole manual with
no terminal, no server and nothing installed — it is grouped by what you
are trying to do and nothing on those pages fetches anything. INDEX.md is
the same index for an editor or a diff.
The same pages are inside the engine, so they are there when you have no
network and something is failing:
docker compose exec revetly revetly manual list
docker compose exec revetly revetly manual show connector-contract
docker compose exec revetly revetly manual export --into revetly-manual
Nothing in that group reads a network or calls your provider.
WHAT YOU MAY DO WITH IT
--------------------------------------------------------------------
Revetly is source-available, not open source. The licence is the
Business Source License 1.1 (BUSL-1.1):
* Non-production use is free and unlimited: evaluating it (on your own real
repository, for as long as you are deciding), development, testing,
personal projects, teaching, and writing a connector against it. No key,
no registration, nobody to tell.
* Production use — running it in support of an organisation's business
operations, including operating an instance for a client — requires a
licence key, issued by the Licensor —
SMG Digital Services sp. z o.o.
* 4 years after a version is first published, that version
converts to the Apache License, Version 2.0. Every
version carries its own date.
The terms are in this folder and inside the image:
0.8.0/LICENSE
0.8.0/THIRD-PARTY-NOTICES what the engine's dependencies oblige
Where the line falls in plain words — what counts as production use, why
internal use across your own teams is not a managed service, what a licence key
is for and how to ask for one — is a page of the manual, readable before or
after you install:
docker compose exec revetly revetly manual show licensing
Licence questions, and licence keys: contact@smgdigitalservices.com
LATER VERSIONS
--------------------------------------------------------------------
`init` writes an `./revetly-update` beside the compose file. Run it to move
to a later engine:
./revetly-update --check what is published, installing nothing
./revetly-update install it
It fetches the release, refuses a tarball whose checksum does not match the
published one, loads it, repoints the `image:` line and restarts the stack —
then rewrites itself with the copy the new engine carries. Your instance is
not touched: sources, docs, `.revetly/`, `.git` and the graph are exactly as
they were, nothing is ingested and nothing is billed. Reconnect your editor's
MCP client afterwards.
Before it swaps anything it asks whether the release can read the data you
already have. A release that needs your stored data migrated is reported and
NOT installed unless you add `--migrate-ok`, and the migration itself is a
command you run afterwards, with its cost stated before anything is spent. A
release older than the engine that wrote your data is refused outright —
installing it would quietly downgrade what is stored.
What each release changed, and the corpus revision it writes, is beside the
tarballs: 0.8.0/CHANGELOG.md. `./revetly-update --check` names the same file for
the release it found, and the commit that release was built from.
AFTER A REBOOT
--------------------------------------------------------------------
Nothing. The compose file `init` writes declares `restart: unless-stopped` on every
service, so a reboot or a Docker daemon restart brings the stack back with no
command from you — and a stack you stopped deliberately (`docker compose stop`)
stays stopped.
The one condition is Docker itself: a restart policy is Docker's, so it only
runs where Docker is running. On macOS that means Docker Desktop set to start
at login (Settings > General > "Start Docker Desktop when you sign in"); on
Linux, `systemctl enable docker`. Where it is not, the stack comes back when
you start Docker, and until then your editor says which container is not
running and names the command that starts it.
PLATFORM
--------------------------------------------------------------------
The commands above are POSIX shell — macOS and Linux. `$PWD` and `$(id -u)`
are not PowerShell; on Windows, run them from a WSL2 shell with Docker
Desktop's WSL integration on.