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.

  • curl and jq for 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, 7285 and 7290 free 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:

  1. Go to Graphs in the workbench and press Try Samples. Both sample graphs are pre-selected; press Create Selected.

  2. 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.

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.