Developer guide
From nothing installed to a working app on Loams, step by step, in your language.
This guide takes you from a machine with nothing on it to an application that writes documents to Loams and runs hybrid search over them. Each step is one page; follow them in order the first time, and come back to the reference pages later.
Loams 0.1.0
These pages describe Loams 0.1.0. 0.x means APIs, on-disk formats and flags may change between
minor versions; loams upgrade moves a self-hosted stack from one release to the next and keeps
its data. Check the feature status
before you depend on something.
The path
Install the CLI or Loams Desktop
Download the loams CLI or Loams Desktop for Linux, macOS or Windows, then check the files against the release checksums and the project's GPG key. Install and verify.
Run the engine on your machine
loams dev runs the whole engine in one process with its data in a local directory. Run Loams locally.
Create a collection and search it
Create a collection with a text field and a vector, write three documents, and run one query that fuses vector and keyword retrieval. First collection and hybrid search.
Call it from your language
Install the SDK for your language and make the first call. SDKs.
Or keep the client you already have
Point a Qdrant, Elasticsearch, Postgres, MySQL or Flight SQL client at Loams. Compatible clients.
Before you ship
Authentication and API keys
The four auth modes, and how to give a script or a CI job an API key.
Consistency tokens
Read your own writes, across processes and services.
Run the whole stack over Tailscale
The 0.1.0 self-hosting path: Docker Compose on your laptop or VM, reached only over your tailnet.
Troubleshooting
The errors people hit first, and what each one means.
Which surface to use
| You want to | Use | Status |
|---|---|---|
| Build a new app with hybrid search | The native REST API on port 8080, or an SDK | Available |
| Call Loams from TypeScript, Python, Go, Rust, C#, C++ or Swift | The SDKs, published as 0.1.0 | Available |
| Call Loams from Java, Kotlin, Ruby or PHP | The SDKs in the repository, not yet published to their registries | Experimental |
| Keep an existing Qdrant or Elasticsearch integration | The Qdrant (6333, 6334) and Elasticsearch (9200) APIs | Available |
| Run SQL with Arrow results | Arrow Flight SQL on port 8082 | Available |
Use psql or a MySQL client over collections | The read-only Postgres and MySQL wire listeners | Available |
To learn why Loams works the way it does, read How Loams works.