# How does Rerun work?

Rerun has several components manage multimodal data across its lifetime. This page explains what they are and how they connect.

## The components

### Logging SDK

The Logging SDK is how you get data into Rerun. Available for Python, Rust, and C++, it runs inside your application and logs data using [archetypes](/content/docs/concepts/logging-and-ingestion/entity-component/index.html) — structured types like `Points3D`, `Image`, or `Transform3D`.

Data can be streamed directly to the Viewer, saved to `.rrd` files, or both.

### Viewer

The Viewer visualizes your data. It comes in two forms:

- **Native Viewer**: A desktop application for Linux, macOS, and Windows
- **Web Viewer**: A browser based application

The viewer includes a [**Chunk Store**](/content/docs/concepts/logging-and-ingestion/chunks/index.html) (in-memory database for logged data) and a **gRPC endpoint** that accepts streamed data from the SDK.

The Web Viewer has performance limitations compared to the native viewer. It runs as 32-bit Wasm and is limited to ~2 GiB memory in practice, limiting the amount of data that can be visualized simultaneously. It also runs single-threaded, making it generally slower than native.

Both viewers can be extended: the Native Viewer through its [Rust API](/content/docs/howto/visualization/extend-ui/index.html), and the Web Viewer can be [embedded in web applications](/content/docs/howto/integrations/embed-web/index.html) or [Jupyter notebooks](/content/docs/howto/integrations/embed-notebooks/index.html).

### Catalog server

The catalog server provides persistent storage and indexing for large-scale data. It organizes data into:

- **Datasets**: Named collections of related recordings
- **Segments**: Individual `.rrd` files registered to a dataset

Data is served via the **redap** protocol ( **Re** run **Da** ta **P** rotocol).

The catalog server is available as:

- Open-source server for local development (`rerun server`)
- **Rerun Hub**, our managed offering for production deployments

### Catalog SDK

The Catalog SDK (`rerun.catalog`) is a Python library for querying and manipulating the data stored on a catalog server. Combined with Rerun Hub, it allows building complex data transformation pipelines.

## How they connect

## What ships where?

### Hosted web viewer

The Web Viewer is available at [rerun.io/viewer](/content/viewer/index.html).
It's a great place to start exploring the examples.

### CLI

The `rerun` binary bundles multiple tools in one:

- **Native Viewer** for visualization
- **OSS catalog server** (via `rerun server`)
- **RRD tools** for file manipulation
- **Web Viewer** (via `rerun --serve-web`)

The Rerun CLI can be downloaded from [GitHub](https://github.com/rerun-io/rerun/releases) or as part of the Python SDK.
It can also be built from source with `cargo install rerun-cli --locked`.

See: [CLI reference](/content/docs/reference/cli/index.html)

### Python SDK

The Python SDK includes:

- **Logging SDK**
- **Catalog SDK**
- **CLI**, including the Viewer (the `rerun` CLI is made available by installing the `rerun-sdk` Python package)

See: Python SDK [installation instructions](/content/docs/getting-started/install-rerun/python/index.html) and [quick start guide](/content/docs/getting-started/data-in/index.html)

### Rust SDK

The Logging SDK as a Rust crate.

See: Rust SDK [installation instructions](/content/docs/getting-started/install-rerun/rust/index.html) and [quick start guide](/content/docs/getting-started/data-in/index.html)

### C++ SDK

The Logging SDK for C++ projects.

See: C++ SDK [installation instructions](/content/docs/getting-started/install-rerun/cpp/index.html) and [quick start guide](/content/docs/getting-started/data-in/index.html)

### The `web-viewer` and `web-viewer-react` NPM packages

These NPM packages bundle the Web Viewer for inclusion on a website.

See: the `web-viewer` package [reference](/content/docs/reference/npm/index.html)

## Common workflows

### Stream to Viewer

The simplest workflow: stream data directly from your code to the Viewer for live visualization.

Minimal example:

C++ Python Rust

````
import rerun as rr

rr.init("rerun_example_log_to_grpc")

# Connect to the Rerun gRPC server using the default address and url: rerun+http://localhost:9876/proxy
rr.connect_grpc()

# Log data as usual, thereby pushing it into the gRPC connection.
while True:
    rr.log("/", rr.TextLog("Logging things…"))
````

Best for: development, debugging, real-time monitoring.

### Save to RRD, view later

Log data to `.rrd` files, then open them in the Viewer whenever needed. Files can be loaded from disk or URLs.

Minimal example:

C++ Python Rust

````
import rerun as rr

rr.init("rerun_example_log_to_rrd")

# Open a local file handle to stream the data into.
rr.save("/tmp/my_recording.rrd")

# Log data as usual, thereby writing it into the file.
while True:
    rr.log("/", rr.TextLog("Logging things…"))
````

And later:

````
$ rerun /tmp/my_recording.rrd
````

Best for: sharing recordings, offline analysis, archiving.

### Store on a catalog server

Register `.rrd` files with a catalog server for persistent, indexed storage. Query and visualize on demand.

Minimal example of creating a dataset and registering files:

````
import rerun as rr

client = rr.catalog.CatalogClient("rerun://example.cloud.rerun.io")
dataset = client.create_dataset("my_data")
dataset.register(["s3://my-rrd-files/recording1.rrd", "s3://my-rrd-files/recording2.rrd"])
````

Best for: large datasets, team collaboration, production pipelines.

### Query and transform data

Use the Catalog SDK to query data from a catalog server, process it, and write results back. Visualization is available at any time.

Minimal example of querying a dataset:

````
import datafusion as dfn
import rerun as rr

client = rr.catalog.CatalogClient("rerun://example.cloud.rerun.io")
dataset = client.get_dataset("my_data")
df = dataset.filter_contents("/obs").reader(index="log_time")  # `df` is a DataFusion dataframe
df.filter(dfn.col("obs:Scalars:scalars").is_not_null()).count()  # count observations in recording
````

Best for: data pipelines, batch processing, ML training data preparation.

Feedback?

Send feedback