Bolt server

relate serve --bolt PORT speaks BoltBolt Neo4j's binary client protocol; relate serve --bolt <port> speaks it, so Neo4j's drivers and Neo4j Browser can run statements against a relate store. Read more in the glossary, Neo4j's binary client protocol, at versions 4.4 and 5.4, so Neo4j's drivers, cypher-shell, and Neo4j Browser can run statements against a relate storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary. Neo4j's Java and Python drivers and cypher-shell refuse the default server agent and connect only when the server runs with --bolt-identity Neo4j/5.26.0 (Compatibility with Neo4j). The same port also serves Bolt over WebSocket for browser clients. Bolt is the transport only: the statements are relate's Cypher, with the differences listed in Differences from Neo4j. Every reply quoted on this page was captured from relate 0.1.2 with a raw Bolt client, PackStream values shown as JSON.

Synopsis

relate serve --database PATH --bolt PORT [--host HOST] [--auth USER:PASSWORD] [--bolt-identity STRING] [--ws-allow-origin ORIGIN] [--ws-max-connections N] [--read-only[=FRESHNESS]]

At startup the server writes where it listens to stderr, with the credential's source:

auth: basic (from --auth)
serve: Bolt listening on bolt://127.0.0.1:8852 (auth: basic)

Handshake

A client opens with the magic bytes 60 60 B0 17 and four version proposals of four bytes each. The server reads them in the client's order, and the first proposal that covers Bolt 4.4 or Bolt 5.4 decides the reply. A proposal 00 RR mm MM covers version MM.m when m lies between mm - RR and mm.

A refused handshake writes one line to the server's stderr, such as bolt: no version proposal covers Bolt 4.4 or Bolt 5.4 (00000005 00000000 00000000 00000000); replying 00000000 and closing connection. The whole negotiation must finish within 5 seconds of the connection being accepted.

HELLO

The SUCCESS of a Bolt 4.4 HELLO that asked for the UTC patch, and of a Bolt 5.4 HELLO:

SUCCESS {"server": "Relate/0.1.2", "connection_id": "conn-1", "hints": {"connection.recv_timeout_seconds": 120}, "patch_bolt": ["utc"]}
SUCCESS {"server": "Relate/0.1.2", "connection_id": "conn-2", "hints": {"connection.recv_timeout_seconds": 120, "telemetry.enabled": false}}

connection.recv_timeout_seconds: 120 tells the driver that a connection silent for 120 seconds is dead; while a statement or a commit runs longer than 60 seconds, the server sends a NOOP chunk (00 00) every 60 seconds to keep it alive.

After a refused HELLO, every message but HELLO and GOODBYE answers IGNORED; a second HELLO fails and closes the connection.

Authentication

A failed check waits 1 second before the FAILURE is sent, on that connection only. The credential is the one relate serve shares with its --http and --mcp listeners. There are no users or roles: CALL dbms.showCurrentUser() reports the authenticated user, or relate under --auth none, with the role admin. Every surface is plaintext, so a credential sent to a non-loopback --host crosses the network unencrypted.

Messages

In auto-commit, a new RUN replaces the open result. Inside a transaction, each RUN keeps its own result, numbered by qid from 0, until COMMIT, ROLLBACK or RESET.

A COMMIT with no transaction open:

FAILURE {"code": "Neo.ClientError.Request.Invalid", "message": "Message of type CommitMessage cannot be handled by a session in the READY state."}

Results and summaries

columnTypes is relate's own key; drivers ignore keys they do not know. Its names are STRING, INTEGER, FLOAT, BOOLEAN, NODE, RELATIONSHIP, PATH, LIST, MAP, POINT, DATETIME, DATE, TIME, DURATION, VECTOR, UUID, BINARY and ANY.

stats holds Neo4j's counters, only the ones that are not zero: nodes-created, nodes-deleted, relationships-created, relationships-deleted, properties-set, labels-added, labels-removed, indexes-added, indexes-removed, constraints-added, constraints-removed, and contains-updates: true. A read carries no stats.

EXPLAIN and PROFILE report the type of the statement they wrap. An auto-commit write, from RUN to the end of its result:

RUN "CREATE (n:Temp {k: $k}) RETURN n.k AS k" {"k": 1} {}
SUCCESS {"fields": ["k"], "columnTypes": ["INTEGER"], "t_first": 2}
PULL {"n": -1}
RECORD [1]
SUCCESS {"bookmark": "relate:2", "stats": {"nodes-created": 1, "properties-set": 1, "labels-added": 1, "contains-updates": true}, "type": "rw", "t_first": 2, "t_last": 0, "parsing_time": 0.000183666, "planning_time": 3.75e-06, "plan_execution_time": 0.002377084, "lex_parse_time": 6.542e-06, "rewrite_time": 3.33e-07, "lower_time": 5.583e-06, "result_generation_time": 3.34e-07, "plan_cache": "miss", "db": "neo4j"}

Plans and notifications

After EXPLAIN the ending SUCCESS carries the plan under plan, after PROFILE under profile, never on the RUN SUCCESS. An EXPLAIN statement returns no records. A plan node has operatorType (with no suffix, such as ProduceResults), args (Id, Details, EstimatedRows when estimated, the measured values on a PROFILE plan, and on the root string-representation, version, planner, planner-impl, planner-version, runtime, runtime-impl and runtime-version), identifiers, children when it has any, and warnings such as {"name": "CartesianProduct"} when it has any. A plan nested deeper than PackStream's 128 levels is replaced by planTruncated: true.

A notification entry has exactly code, title, description (the remedy appended as (remedy: <remedy>)), severity and category. A statement without EXPLAIN or PROFILE derives none. At Bolt 5.4, notifications_minimum_severity (INFORMATION, WARNING or OFF) and notifications_disabled_categories in the HELLO, BEGIN or RUN extra filter the list; a statement's keys override the HELLO's.

Bookmarks

The SUCCESS that ends an auto-commit statement that wrote, and the SUCCESS of a COMMIT that wrote, carry a bookmarkbookmark The marker a commit returns, relate:<n>, naming its place in the store's commit sequence; returned by the clients and over Bolt. Read more in the glossary, relate:<n>: the store's commit sequence number, shared with every other surface and client that commits to the store. A read, a write that changed nothing and an EXPLAIN carry none. Bookmarks a client sends in BEGIN or RUN are accepted and ignored: one process serves one store, so every commit is already visible to the next statement on any connection.

Namespaces

A RUN in auto-commit and a BEGIN choose their namespace with the extra's db; without db, or with null or "", it is neo4j, and the choice does not carry over to the next request. A RUN inside a transaction uses the namespace of its BEGIN. The ending SUCCESS names it in db. An unknown name fails the RUN with Neo.ClientError.Database.DatabaseNotFound and semantic error: DatabaseNotFound: Graph not found: <name>. The system namespace accepts only procedure calls (CALL, YIELD, RETURN) and SHOW commands.

Type mapping

Results encode as PackStream values and structures, at any depth inside a list or map:

The 5.4 element idselement id The string elementId() returns for a node or relationship, such as 4:relate-neo4j:n0; it stays the same when the store is closed and opened again. Read more in the glossary are the strings elementId() returns, such as 4:relate-neo4j:n0 for a node and 5:relate-neo4j:r0 for a relationship. Graph values from the system namespace have no element id, so a 5.4 result that holds one fails with elements of this namespace have no element ids. A Bolt 5.4 read of a node and a relationship:

RECORD [{"struct": "0x4E", "fields": [0, ["Person"], {"name": "Ada", "role": "engineer"}, "4:relate-neo4j:n0"]}, {"struct": "0x52", "fields": [0, 0, 3, "WORKS_ON", {"since": 2024}, "5:relate-neo4j:r0", "4:relate-neo4j:n0", "4:relate-neo4j:n3"]}]

Parameters decode by the same table in reverse, temporal, duration, and point structures included. A byte array parameter lives only inside the statement: storing it as a property fails with Neo.ClientError.Statement.TypeError. A parameter the engine cannot represent fails the RUN with Neo.ClientError.Request.Invalid and a message naming its path, such as unsupported parameter value for $p: Struct(0x46); this happens to the legacy DateTime structures 0x46 and 0x66 on a 5.4 connection. A point's SRID must be 4326, 4979, 7203, or 9157.

Failure codes

Every FAILURE carries a Neo4j status code, so a driver classifies it as it would a Neo4j error. The message is the engine's own.

A failure while the statement runs is reported at the first PULL or DISCARD: the RUN answers SUCCESS with its fields and ANY for every column type, and the PULL answers the FAILURE with no records. Inside a transaction, the failure also fails the transaction, and ROLLBACK or RESET ends it. The server never retries a conflict; a driver's managed transaction retries Neo.TransientError codes. The detail of an internal failure goes to the server's stderr, never to the client. Each error's cause and remedy is in the Bolt errors.

RUN "RETURN 1/0 AS x" {} {}
SUCCESS {"fields": ["x"], "columnTypes": ["ANY"], "t_first": 0}
PULL {"n": -1}
FAILURE {"code": "Neo.ClientError.Statement.ArithmeticError", "message": "type error: / by zero"}

WebSocket

The Bolt port also accepts a WebSocket upgrade (ws://), which the browser build of Neo4j's JavaScript driver and Neo4j Browser use. Authentication runs unchanged inside the WebSocket session, and WebSocket connections count against --max-connections.

--ws-max-connections N caps concurrent WebSocket sessions (default unlimited, RELATE_WS_MAX_CONNECTIONS); an upgrade over the cap is closed with no response. A value that is not an origin URL or * stops the server before it starts, and so does --bolt-identity without --bolt:

relate serve --database :memory: --bolt 7687 --read-only --ws-allow-origin example.com
echo "exit=$?"
relate serve --database :memory: --http 7474 --read-only --bolt-identity Neo4j/5.26.0
echo "exit=$?"

Error: serve --ws-allow-origin expects an origin URL (http(s)://…) or *, got "example.com"
Usage: relate serve --database PATH [--host HOST] [--http PORT] [--origin ORIGIN] [--mcp PORT|stdio] [--bolt PORT [--bolt-identity STRING] [--ws-allow-origin ORIGIN] [--ws-max-connections N]] [--read-only[=FRESHNESS]] [--load SOURCE] [--auth USER:PASSWORD] [--concurrent-logical-workspace-limit SIZE] [--max-traversal-depth N] [--expression-memory-limit SIZE] [--safe | --no-safe] [--logical-graph-size-limit SIZE] [--durability-mode MODE] [--snapshot-format F]
Run 'relate serve --help' for more information.
exit=2
Error: serve --bolt-identity configures the --bolt surface, which this run does not serve: pass --bolt PORT or drop --bolt-identity
Usage: relate serve --database PATH [--host HOST] [--http PORT] [--origin ORIGIN] [--mcp PORT|stdio] [--bolt PORT [--bolt-identity STRING] [--ws-allow-origin ORIGIN] [--ws-max-connections N]] [--read-only[=FRESHNESS]] [--load SOURCE] [--auth USER:PASSWORD] [--concurrent-logical-workspace-limit SIZE] [--max-traversal-depth N] [--expression-memory-limit SIZE] [--safe | --no-safe] [--logical-graph-size-limit SIZE] [--durability-mode MODE] [--snapshot-format F]
Run 'relate serve --help' for more information.
exit=2

Limits

Every row is a limit. relate serve has no flag for the rows marked fixed.

There is no statement timeout on relate serve, and no TLS: on a non-loopback --host the server starts with a warning that every surface is plaintext, and a TLS-terminating proxy in front of it is the way to encrypt.

Not supported

Compatibility with Neo4j

relate's engine repository keeps a compatibility record for this server (docs/api/bolt/compatibility.md), from three probes against Neo4j 2026.09.0 Community: a raw-socket wire probe at Bolt 4.4 with the boltkit tool, a probe through the neo4rs Rust driver 0.9.0-rc.10, and a probe at Bolt 5.4 on 2026-11-02. Each finding compares a driver-visible behavior of the two servers. A finding is compatible when the replies were equal, fixed when a change to relate made them equal, deferred when relate keeps a different reply on purpose, and not implemented when it was decided against. This table restates its counts:

The fixes made relate's replies match Neo4j's in summary metadata, bookmarks, several open results in one transaction, the receive-timeout hint and keep-alives, HELLO validation, protocol breaches, RESET, ROUTE, failure codes, missing parameters, temporal and point structures, byte array parameters, the UTC patch and the w/rw query types. The Bolt 5.4 probe settled the version replies, the 5.x HELLO, LOGON and LOGOFF, TELEMETRY, element ids, the UTC DateTime structures, and the notification filters.

What still differs from a Neo4j server:

Two of these affect drivers, as the record states for the driver versions it tested. Neo4j's Java driver from 5.0 and Python driver 5.23 to 5.28 refuse a server agent that does not start with Neo4j/; --bolt-identity Neo4j/5.26.0 sends that agent verbatim, and the record says those drivers then connect, which is a compatibility setting, not a claim of feature parity. The Go driver 5.28.5 does not check the agent. Code shared between relate and Neo4j can tell them apart with CALL dbms.components(), which on relate returns Neo4j Kernel with the version 2026.10-relate, then Cypher with 5 and 25, then Relate with the relate version.

See also

• relate serve: every serve flag
• Serve a store over Bolt: connecting Neo4j's drivers and Neo4j Browser
• Bolt errors: each error with its cause and remedy
• Differences from Neo4j: the Cypher the server runs
• HTTP Query API: the JSON surface served by the same process
• Security: the defaults of every served surface