Skip to main content

Security

View as Markdown

An overview of how RocketRide handles credentials, network exposure, and authentication across its components.

Credential isolation​

API keys are configured per node inside the pipeline definition. Each node holds only its own credentials — there are no shared global secrets, no credential store, and no key that grants access to more than one provider.

{
"id": "llm_1",
"provider": "llm_openai",
"config": {
"profile": "openai-4o",
"openai-4o": { "apikey": "${ROCKETRIDE_OPENAI_KEY}" }
}
}

Nodes use ${ENV_VAR} substitution so the key itself never has to appear in the .pipe file. Only ROCKETRIDE_-prefixed variables are substituted — a reference to any other variable is replaced with <REDACTED>. See Best Practices: Credential management for how to keep keys out of version control.

Pipeline process isolation​

Each running pipeline is a separate engine process (a task). A task does not inherit the engine's full environment, only an allowlist:

  • process basics: PATH, HOME, locale, TLS and proxy settings
  • interpreter and ML runtime settings (PYTHON*, HF_*, CUDA_*, and similar)
  • every ROCKETRIDE_ variable except five the engine removes: ROCKETRIDE_DB_BROKER_URL, ROCKETRIDE_DB_BROKER_TOKEN, ROCKETRIDE_DB_DSNS, ROCKETRIDE_DB_DSN, and ROCKETRIDE_DB_RESOLVE_ERROR. A task that uses a RocketRide database node then gets ROCKETRIDE_DB_DSNS, holding the DSN of each database the run was approved for. Any other ROCKETRIDE_DB_* name passes through like the rest.
  • what nodes and the task itself use directly: RR_STORE_URL, RR_STORE_SECRET_KEY, RR_SIGNING_KEY, RR_BASE_URL, RR_CORS_ORIGINS, RR_OAUTH_BROKER_URL, RR_PROC_PRIVATE, MEDIA_TOOLKIT_FFMPEG, AWS_*, and the API-key fallbacks individual node pages document (such as OPENAI_API_KEY)

Pipeline code can read everything on that list. Any other engine setting stays in the engine.

VariableEffect
RR_SUBPROCESS_ENVExtra variables to pass to tasks: names separated by commas or spaces, a trailing * for a prefix (SLACK_BOT_TOKEN,GH_*). A bare * passes the whole environment except RR_TASK_TOKEN_KEY, which tasks never get, and the five ROCKETRIDE_DB_ variables the engine removes (listed above); use a bare * only on a single-user install.
RR_PROC_PRIVATE1 makes the engine and each task restrict their sensitive /proc/<pid> entries (environment, memory, open files) to root. Linux only. Hosted engines turn this on automatically.

Set both in the engine's own environment or its .env file. Pipelines cannot change RR_ variables.

Limits of RR_PROC_PRIVATE:

  • Entries such as cmdline and status stay readable to everyone.
  • A process is covered only after its startup code has run, and only that process: other programs the engine or a task starts are not covered.
  • While a crash dump is being written, the crashing process is readable again.
  • Same-user debuggers (gdb, py-spy) can no longer attach, and the kernel writes no core dumps for these processes.
  • A task that cannot make itself private exits without running pipeline code. If the engine itself cannot, it logs a warning and keeps serving.

For strict separation between pipelines, run them under different OS users or in separate containers.

Network exposure​

The engine binds to localhost by default:

  • Port 5565 — WebSocket API (SDK / CLI connections).
  • Source-node HTTP endpoints (Webhook, Chat, Dropper) — the port is set per node in the pipeline config; 5567 is the conventional choice used in examples and integrations, not a fixed engine bind.
  • Task data ports — each running pipeline listens on localhost, on a port from a pool that starts at --base_port (20000 by default), for the engine only. It accepts a connection only with that pipeline run's own token, which the engine keeps and replaces on every start; the pipeline's process is given only a hash of it. The engine connects as soon as the process reports its listener, and over that connection the process may ask the engine only for the commands the engine registered for it — today one, spend.check, which asks whether the run's own organization may open a pipe. Its /status endpoint accepts only that token.

Only the source-node HTTP port needs to be accessible to external callers when you're using a webhook-based source. Port 5565 is a management interface; expose it only to trusted clients on a private network or behind a VPN.

For production deployments, put the engine behind a reverse proxy (nginx, Caddy, AWS ALB) that terminates TLS and enforces rate limiting before traffic reaches the engine.

Endpoint authentication​

When a Webhook, Chat, or Dropper source node starts, the engine generates two credentials and writes them to the Project Log:

  • Public authorization key - presented by external callers in the Authorization: Bearer <key> header. Safe to share with trusted API clients. It is accepted only while the run's source is a Webhook, Chat, Dropper, Discord or Telegram node: on any other run it authenticates nothing.
  • Private token - the internal credential for the endpoint. Used by the SDK to connect to a running task via --token. Do not share this publicly.

The Project Log is local to the operator who started the pipeline (it is not a shared or exportable log), so the private token is only visible to that operator. Retrieve it from your own Project Log when you need to connect a client with --token.

The private token is an HMAC of the run's identity under the engine's RR_TASK_TOKEN_KEY, so it cannot be worked out from the project, source or owner. A relaunch of the same run gets the same private token while the key stays the same. Without RR_TASK_TOKEN_KEY the engine uses a random key of its own process, and the private token changes whenever the engine restarts. Set the key (at least 32 characters, the same value on every replica) to keep it. The engine never passes the key to pipeline code, even when RR_SUBPROCESS_ENV names it. Tasks run as the engine's OS user, so on Linux set RR_PROC_PRIVATE=1 (hosted engines do this already) or a task can read the engine's /proc/<pid>/environ; and keep the key out of any file the task can read, such as the engine's .env, on an engine shared by several users.

MCP authentication​

The engine's built-in MCP server (/mcp) accepts two credentials and rejects everything else:

  • OAuth access token, for Claude, ChatGPT and other OAuth clients. The client discovers the sign-in flow from the endpoint itself.
  • RocketRide API key (rr_...), sent as Authorization: Bearer rr_..., for Cursor, scripts and anything else that can set a header.

Task-scoped keys (tk_/pk_) and PKCE exchange codes (cd_) never grant access to /mcp. The only exception is the MCP_DEV_NO_AUTH=1 development bypass, which the engine honors only on a loopback address. A self-hosted engine on a non-loopback address refuses OAuth tokens until MCP_EXPECTED_AUDIENCE is set; see Self-hosting the MCP server.

Pipeline file security​

A .pipe file is plain JSON. When you use ${ENV_VAR} substitution, the key stays in the environment and never touches disk in the pipeline file. When you embed a key directly (for quick local testing), it is stored in plain text — treat the file as a secret.

Do not commit .pipe files containing embedded credentials to version control. Add them to .gitignore:

*.pipe

In CI/CD, pass the pipeline file through a secrets-expansion step before passing it to rocketride start, or inject keys via environment variables and use ${...} references.

Dependency scanning​

The RocketRide codebase runs automated dependency scanning: CodeQL via GitHub's default setup, plus Trivy and OpenSSF Scorecard on pushes to develop/main and on scheduled runs. See Security for the vulnerability reporting process and SLA.