Skip to main content

Use RocketRide from a coding agent

View as Markdown

This page is the shortest path for a coding agent (or the person driving one) to start using RocketRide. Each section is a few lines of copy-paste commands with a link to the page that has the detail.

What RocketRide is​

RocketRide is an open source AI meta-harness with the only enterprise-grade runtime built on C++. Designed for professional software developers and technical builders, whether solo or teams or organizations, to enable them to easily build, stage, test, publish and maintain agents and AI-enabled applications that scale in production. Leverage directly from an IDE with the VS Code extension, from the terminal with the CLI, from code with the Python or TypeScript SDK, or dynamically using the MCP server.

Open source, MIT licensed. Nodes cover LLM providers, vector stores, OCR, NER, PII anonymization and more.

Run the engine locally​

There are four ways to run the engine. Pick one:

  • VS Code extension: for people working in an editor. It downloads and manages a local engine for you. See Build in your IDE.
  • Native download: for machines without Docker. Download the engine archive for Linux, macOS or Windows and run it directly.
  • RocketRide Cloud: for when you do not want to run anything locally. Skip to the hosted section below.
  • Docker: for any machine that runs Docker. The rest of this page uses it, because the command is the same everywhere.

The engine ships as a container image. If a container named rocketride-engine already exists (the VS Code extension creates one with this name), do not remove it. Either use that engine and skip this step, or give this one another name and host port. Then run:

docker run -d --name rocketride-engine --platform linux/amd64 \
-p 127.0.0.1:5565:5565 \
-v rocketride-data:/opt/data \
--restart unless-stopped \
-e ROCKETRIDE_APIKEY=rr_local \
-e ROCKETRIDE_URI=ws://127.0.0.1:5565 \
ghcr.io/rocketride-org/rocketride-engine:latest

To run it next to an existing engine, change only --name and the host side of -p (for example 127.0.0.1:5566:5565). Leave -e ROCKETRIDE_URI=ws://127.0.0.1:5565 in the Docker command as it is: that address is inside the container. Then use the new host port everywhere below that shows localhost:5565: the health check, the ROCKETRIDE_URI you export in your shell, and the MCP address.

  • The command is the same on every machine. The image is amd64 only: --platform linux/amd64 is required on Apple Silicon (Docker runs it under emulation, and the port can take 15 seconds or more to answer there) and has no effect on Intel or AMD machines.
  • ROCKETRIDE_APIKEY=rr_local sets the key clients must send. The value can be any string that starts with rr_: the built-in MCP server refuses other values, and the CLI and SDK must send the same one.
  • ROCKETRIDE_URI=ws://127.0.0.1:5565 tells the engine's MCP server to run tool calls against this engine. Engine image 3.6.0 and earlier need it: without it (and without MCP_RESOURCE_IDENTIFIER), an engine that is not bound to localhost connects tool calls to RocketRide Cloud instead. Setting it is always safe (see Use it over MCP locally).

More: Run the Engine in Docker.

Check it is up​

curl http://localhost:5565/version

It answers 200 with {"status":"OK","data":{"version":"..."}} and needs no key. Every other unknown path, such as /ping, answers 401.

Use it from the CLI or SDK​

Install the Python package (Python 3.10 or newer) in a virtual environment. It installs the rocketride command while the environment is active. The commands are joined with &&, so the block stops at the first line with a clear message if python3 is too old (the python3 that ships with macOS is 3.9); if it stops, use a newer interpreter in both places, for example python3.12:

python3 -c "import sys; sys.exit(None if sys.version_info >= (3, 10) else 'RocketRide needs Python 3.10 or newer')" &&
python3 -m venv .venv &&
source .venv/bin/activate &&
pip install rocketride

For Node, use npx rocketride. npm install rocketride does not put the command on your path. Node users run every rocketride command on this page as npx rocketride.

Point the client at the engine. The key must match the one the engine was started with:

export ROCKETRIDE_URI=ws://localhost:5565
export ROCKETRIDE_APIKEY=rr_local

Save this pipeline as code.pipe. It reads a source file, splits it into its functions and classes, and fingerprints it, all in two branches from one input. It needs no model provider key and no account:

cat > code.pipe <<'EOF'
{
"components": [
{ "id": "in", "provider": "webhook", "config": {} },
{ "id": "parse", "provider": "parse", "config": {}, "input": [{ "lane": "tags", "from": "in" }] },
{ "id": "code", "provider": "preprocessor_code", "config": {}, "input": [{ "lane": "text", "from": "parse" }] },
{ "id": "parts", "provider": "response_documents", "config": {}, "input": [{ "lane": "documents", "from": "code" }] },
{ "id": "text", "provider": "response_text", "config": {}, "input": [{ "lane": "text", "from": "parse" }] },
{ "id": "hash", "provider": "hash", "config": {}, "input": [{ "lane": "tags", "from": "in" }] },
{ "id": "sum", "provider": "response_hash", "config": {}, "input": [{ "lane": "tags", "from": "hash" }] }
],
"source": "in"
}
EOF

Validate it and start it:

rocketride validate code.pipe
rocketride start --pipeline ./code.pipe

start prints a task token and exits; the pipeline keeps running on the engine. Stop it before the next step with rocketride stop --token <token>. It does not print an address. The token is what you pass to rocketride stop --token <token>, rocketride upload --token <token>, and client.send(token, ...) in the SDK. Keep "source": "in": this example's webhook has an empty config, so the engine cannot work out the source by itself. Without it, start fails even though validate passes. The error is Pipeline has no source. Select a source component or add a node configured as a source. (on engine 3.6.0 and earlier: Pipeline does not have a source component defined). Engines newer than 3.6.0 also warn at validate: Pipeline has no source component: ....

Send code and read the reply​

This script starts code.pipe, sends a short Python file, prints each result, checks all three and stops the task. It reads ROCKETRIDE_URI and ROCKETRIDE_APIKEY from the environment, so run it in the same shell and folder:

import asyncio
import hashlib
from rocketride import RocketRideClient

SOURCE = b"""import os


class Greeter:
def hello(self, name):
return "hi " + name


def add(a, b):
return a + b
"""


async def main():
async with RocketRideClient() as client:
result = await client.use(filepath='code.pipe')
token = result['token']
out = await client.send(token, SOURCE, objinfo={'name': 'greeter.py'})
await client.terminate(token)

parts = [doc['page_content'] for doc in out['documents']]
for part in parts:
print(repr(part))
print(repr(out['text'][0]))
print(out['hash'][0][:16] + '...')

assert len(parts) == 4
assert any(part.startswith('def add') for part in parts)
assert SOURCE.decode() in out['text'][0]
assert out['hash'][0] == hashlib.sha512(SOURCE).hexdigest()
print('ok')


asyncio.run(main())

It prints:

'import os'
'class Greeter:\n def hello(self, name):\n return "hi " + name'
'def hello(self, name):\n return "hi " + name'
'def add(a, b):\n return a + b'
'import os\n\n\nclass Greeter:\n def hello(self, name):\n return "hi " + name\n\n\ndef add(a, b):\n return a + b\n\n\n\n'
9b3ea02fd87ae7bd...
ok

The reply has three results, each from its own node:

  • documents (response_documents, after preprocessor_code): one document for the import, the class, the method and the function. The method shows up twice, once inside the class and once on its own. The check is 4 documents and one starts with def add.
  • text (response_text, after parse): the text the parser read from the file, which holds the source you sent (with a few extra newlines at the end). The check is that the source is inside it.
  • hash (response_hash, after hash): the SHA-512 fingerprint of the bytes you sent. The check recomputes it with hashlib and compares.

Both branches start from the tags lane of the webhook. A branch that reads another lane of the same source can return nothing for the other branch, with no error.

The pipeline needs no model provider key and no account. A first run on a fresh engine took about 13 seconds on a laptop, and later runs took 5 to 9 seconds. Starting the engine is separate and not counted.

More: Run from the CLI, CLI Reference, Python SDK, TypeScript SDK.

Use it over MCP locally​

A running engine serves MCP at http://localhost:5565/mcp. Send the key you started the engine with as a bearer token:

Authorization: Bearer rr_local

Claude Code:

claude mcp add --transport http rocketride-local http://localhost:5565/mcp --header "Authorization: Bearer rr_local"

On engine image 3.6.0 and earlier, when neither ROCKETRIDE_URI nor MCP_RESOURCE_IDENTIFIER is set on a Docker engine (or any engine not bound to localhost), initialize and tools/list still work, but every tool call connects to RocketRide Cloud and fails with Invalid or revoked API key. Start the engine with the command above to avoid this. A local Docker engine offers 32 tools (send_files needs a loopback bind).

Use the hosted server​

The hosted MCP server is at https://api.rocketride.ai/mcp.

claude mcp add --transport http rocketride https://api.rocketride.ai/mcp

Claude Code then lists the server as needing authentication. Run /mcp in Claude Code and pick the server to finish the browser sign-in (OAuth). Clients that can send headers can use a RocketRide API key instead: Authorization: Bearer rr_.... For the CLI against RocketRide Cloud, rocketride login --uri https://api.rocketride.ai signs in through the browser and saves ROCKETRIDE_URI and ROCKETRIDE_APIKEY (and the ROCKETRIDE_DEPLOY_* pair) to .env. Without a browser, create a key in the web app and run rocketride login --uri https://api.rocketride.ai --apikey <key>. Run unset ROCKETRIDE_URI ROCKETRIDE_APIKEY first if you exported them in the steps above: a value exported in the shell wins over the one login saves to .env, so the CLI would keep talking to the local engine.

More: Connect a Client and HTTP MCP Server.

Environment variables​

The SDKs and the CLI read the same two variables.

VariableLocal engineRocketRide Cloud
ROCKETRIDE_URIws://localhost:5565wss://api.rocketride.ai
ROCKETRIDE_APIKEYthe same value the engine was started with (any non-empty value if the engine has none)your rr_ API key

Component names​

Take a pipeline's provider values from the MCP list_components tool or from the component reference, not from memory. For example, the MCP validate_pipeline tool accepts response_text as the response component.

Machine-readable docs​

  • /llms.txt: an index of every page with a one-line description.
  • /llms-full.txt: the full text of every page in one file.
  • Any page as markdown: drop the trailing slash from its URL and add .md, for example https://docs.rocketride.org/quickstart.md.

Go deeper​