Getting started
From nothing to a running engine, a search and a graph query. Budget about ten minutes, most of it waiting for the first start.
What you need
-
Docker, any recent version. No JDK, no database, no search cluster.
-
4 GB of memory available to the container. 6 GB is more comfortable if you intend to load a larger dataset.
-
curlandjqfor the REST steps further down. Only those steps need them - the console, and everything you can reach from it, needs nothing but Docker. -
Ports
7280,7281,7282,7285and7290free on your machine. If some are taken, see Troubleshooting.
The image is multi-architecture, so Apple Silicon and ARM servers run natively without emulation.
1. Start it
docker run --rm --name cyrock-db \
-p 7280:7280 -p 7281:7281 -p 7282:7282 -p 7285:7285 -p 7290:7290 \
-v cyrock-db-data:/data \
-e JAVA_OPTS=-Xmx3g \
cyrockai/db:1.0.0
Two flags worth keeping. The named volume is what makes your data survive a restart - leave -v off
for a throwaway run. And --name cyrock-db is what lets every later docker logs cyrock-db or
docker exec cyrock-db … in this manual find your container; without it Docker assigns a random
name and those commands have nothing to match.
First start takes 30 to 60 seconds while the engine creates its storage and seeds a tenant. You can watch for readiness rather than guess:
docker ps # the STATUS column shows "health: starting", then "healthy"
2. Read the startup banner
When it is ready, the container prints a banner. It holds the three things you need:
==========================================================
CYROCK.AI DB UI ready at http://localhost:7280
Login (super-admin): superadmin / superadmin
Login (admin): defaultadmin / defaultadmin
Login (member): member / member
Platform REST API: http://localhost:7281
Platform gRPC: localhost:7291
Data REST API: http://localhost:7282
Data gRPC: localhost:7292
Client gRPC gateway: localhost:7290
MCP endpoint: http://localhost:7285/mcp
Project ID: 3613a31d-9829-4e01-8525-c436a34eb704
Storage: /data
API key (REST / SDKs / MCP):
H1-q5LPq5j9_hVfpO8tIuKzIEC3Il98nPgOoh5iTJws
Also cached in /data/bootstrap-state.properties
==========================================================
The banner is printed from inside the container, so it lists every port the engine bound - not the ones
you can reach. The addresses that work from your machine are those you published with -p, which is why
localhost:7280 works while localhost:7291 and localhost:7292 do not: the docker run above
publishes neither. That is deliberate. The client gateway on 7290 fronts both planes and is the only
gRPC port the SDK needs, so the other two stay internal.
Keep the API key and the project ID to hand - every programmatic interface needs them. Both
are also written to bootstrap-state.properties in the storage directory, so you can recover them
later without restarting:
docker exec cyrock-db cat /data/bootstrap-state.properties
The three logins are seeded at different role levels so you can see what each role can do. They are in-memory evaluation accounts; a real deployment authenticates against your identity provider.
3. Log in to the console
Open localhost:7280 and sign in as superadmin / superadmin.
You land on the admin area, which shows the seeded organization, project and users. The workbench is where you work with data.
4. Load a sample dataset
Rather than starting empty:
-
Go to Graphs in the workbench and press Try Samples. Both sample graphs are pre-selected; press Create Selected.
-
Do the same in Collections - the next step uses one of those.
The graphs are a movies graph and a retail graph, with nodes, typed edges and vector embeddings already computed. The collections are three document sets, including an FAQ knowledge base and a movies collection.
Loading takes a few seconds per dataset; progress is shown per template.
5. Your first search
Open the movies collection and switch to the query view. Search in CyQL reads as a clause on a normal match:
MATCH (d)
SEARCH 'godfather' ON title TOP 5
RETURN d.title, score(d)
Two of the sample films match. SEARCH is BM25 keyword scoring, so it needs no embedding provider -
only a field indexed for full text, which title is in this collection. score(d) gives the score,
and it takes the variable it scores: a bare score() will not parse.
Documents have no labels, which is why the pattern is (d) rather than (d:Something).
Vector search is the sibling clause:
MATCH (d)
SIMILAR TO $qv ON vector TOP 5
RETURN d.title, score(d)
Worth knowing before you try it: the seed can be a vector or text. $qv is a vector - an
embedding you supply with the query - so by hand it means producing a 384-number array first. That is
what the movies sample uses: its vector field is bring-your-own-vector, with no embedding model. A
field created with a MODEL (and an embedding provider configured on the server) also accepts a
text phrase - SIMILAR TO 'a movie about time travel' ON embedding TOP 5 - and embeds it for you, so
you skip the array. The console and the SDKs - Java and Python - are
the comfortable ways in.
6. Your first graph query
Now open the movies graph. Search finds a record; a graph tells you what surrounds it. Traversal uses arrow patterns:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE m.title = 'The Matrix'
RETURN p.name
Reading the same edge from the other end works with the undirected form, which follows it either way:
MATCH (m:Movie)-[:ACTED_IN]-(p:Person)
WHERE m.title = 'The Matrix'
RETURN m.title, p.name
Search and traversal also combine in a single MATCH, which is the point of the engine - find records,
then expand through what they are connected to. That needs a searchable field on the graph, and the
sample graph has none, so CyQL is where to pick that up along with the rest of the
language.
7. Your first REST call
Each server wants a different credential, which is the thing worth getting straight up front:
-
Platform (
7281) - definitions and tenancy - takes the API key directly. -
Data (
7282) - documents, search, queries - takes a short-lived token, valid 300 seconds, that you exchange the API key for.
API_KEY=<the key from the banner>
PROJECT_ID=<the project ID from the banner>
# Platform: list this project's collections, using the API key.
curl -sS "http://localhost:7281/api/v1/projects/$PROJECT_ID/collections" \
-H "X-API-Key: $API_KEY"
# Data: exchange the key for a token, then use the token.
TOKEN=$(curl -sS -X POST http://localhost:7281/api/v1/token \
-H "X-API-Key: $API_KEY" | jq -r .token)
curl -sS "http://localhost:7282/api/v1/collections/<collection-id>/documents" \
-H "Authorization: Bearer $TOKEN"
Sending the bearer token to the platform server returns 401; sending the raw API key to the data
server does too. REST API explains why.
Both servers publish an interactive Swagger UI, which is the easiest way to explore the rest of the surface - localhost:7281/swagger-ui for platform operations and localhost:7282/swagger-ui for data operations. See REST API.
Where to go next
-
Understand the model - Concepts explains collections against graphs, and when to reach for which.
-
Use it from Java - Java SDK. The connection needs no port argument.
-
Use it from Python - Python SDK. The same operations, blocking or
async. -
Connect an agent - MCP wires Claude to the engine’s 40 tools.
-
Use your own embedding provider - Configuration. Embeddings are in-process by default and need no account, so this is only worth reading when you want a specific model.
-
Keep it running - Operations covers volumes, backup, health and sizing.