# How to Get Started with RLM: Examples, Tutorials, and Quick-Start Guide

> Get started with RLM using the alexzhang13/rlm repository. Access quick-start scripts, detailed examples, and tutorials for efficient RLM implementation.

- Repository: [az/rlm](https://github.com/alexzhang13/rlm)
- Tags: getting-started
- Published: 2026-06-18

---

**Yes, the alexzhang13/rlm repository provides a comprehensive quick-start script, nine standalone example files, and detailed markdown documentation covering everything from basic client initialization to advanced sandboxed execution.**

Recursive Language Models (RLM) provide a flexible inference engine that enables language models to interact with REPL environments, make sub-LM calls, and handle arbitrarily long contexts. The repository ships with complete **RLM examples and tutorials** that demonstrate how to use the `RLM` client, configure REPL environments, and log execution trajectories for visualization.

## Core Architecture Components

Understanding the codebase structure helps navigate the examples effectively. The repository implements four primary components:

1. **`RLM` client** – Located in [`rlm/core/rlm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py), this wraps language-model providers (e.g., OpenAI, Anthropic) and replaces standard completion calls with `rlm.completion(prompt)`. It tracks usage and returns an `RLMChatCompletion` object containing trajectory metadata.

2. **REPL environments** – Defined in [`rlm/environments/base_env.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/base_env.py), these provide either non-isolated execution (`LocalREPL`) or isolated sandboxes (Docker, Modal, Prime). They inject helper globals including `llm_query`, `rlm_query`, `context`, `answer`, and `SHOW_VARS` that generated code can invoke.

3. **LM-handler server** – Implemented in [`rlm/core/lm_handler.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py), this multi-threaded TCP server receives JSON-encoded requests from REPLs and forwards them to the appropriate client, enabling sub-calls to be routed back to the host.

4. **Logging and visualization** – The `RLMLogger` class in [`rlm/logger/rlm_logger.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/logger/rlm_logger.py) records entire call graphs to JSONL files for replay in the visualizer tool.

## Quick-Start Example

The fastest way to begin is with [`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py), which demonstrates minimal client creation and a single completion call. After installing the package (`pip install rlms`) and configuring your API key, you can run:

```python
from rlm import RLM

# Initialize the RLM client

rlm = RLM()

# Execute a simple completion

response = rlm.completion("What is the capital of France?")
print(response)

```

This script showcases basic client instantiation from [`rlm/core/rlm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py) and optional logging configuration.

## Complete List of RLM Examples

The repository includes nine standalone scripts in the `examples/` directory, each targeting specific use cases:

### Basic Usage

- **[`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py)** – Minimal end-to-end run showing client creation and `completion` calls.
- **[`examples/lm_in_repl.py`](https://github.com/alexzhang13/rlm/blob/main/examples/lm_in_repl.py)** – Demonstrates how the model can call `llm_query` inside generated Python code using the default `LocalREPL`.

### REPL Environment Variants

- **[`examples/docker_repl_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/docker_repl_example.py)** – Launches a sandboxed Docker container using `DockerREPL` for safe code execution.
- **[`examples/modal_repl_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/modal_repl_example.py)** – Runs in a Modal sandbox (requires `modal` SDK) demonstrating the HTTP-broker pattern.
- **[`examples/prime_repl_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/prime_repl_example.py)** – Executes in a Prime sandbox (requires `prime` extra) using Prime's sandbox API.

### Advanced Patterns

- **[`examples/rlm_query_batched_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/rlm_query_batched_example.py)** – Shows efficient handling of multiple prompts via `rlm_query_batched` for parallel sub-calls.
- **[`examples/custom_tools_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/custom_tools_example.py)** – Registers user-defined functions that the model can invoke, extending the REPL with domain-specific helpers.
- **[`examples/depth_metadata_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/depth_metadata_example.py)** – Retrieves full call-graph metadata after execution, useful for debugging recursion depth.
- **[`examples/logger_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/logger_example.py)** – Captures execution trajectories to disk using `RLMLogger(log_dir="./logs")` for later inspection with the visualizer.

## Key Documentation Files

Beyond executable scripts, the repository provides written tutorials:

- **[`docs/getting-started.md`](https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md)** – Step-by-step installation, configuration, and first-run guide.
- **[`docs/architecture.md`](https://github.com/alexzhang13/rlm/blob/main/docs/architecture.md)** – In-depth description of the REPL-LM-handler architecture and communication protocols.

## Running the Examples

To execute any example:

1. Install the package: `pip install rlms`
2. Set required API keys (e.g., `OPENAI_API_KEY`)
3. Run the desired script: `python examples/quickstart.py`

For sandboxed examples (Docker, Modal, Prime), ensure the respective SDK and permissions are configured according to [`docs/getting-started.md`](https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md).

## Summary

- The **quick-start script** ([`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py)) provides the minimal code needed to initialize an `RLM` client and execute completions.
- **Nine standalone examples** cover local execution, Docker/Modal/Prime sandboxes, batched queries, custom tools, and trajectory logging.
- Core implementation resides in [`rlm/core/rlm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py) for the client, [`rlm/core/lm_handler.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py) for the server, and `rlm/environments/` for REPL implementations.
- **Documentation** in [`docs/getting-started.md`](https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md) and [`docs/architecture.md`](https://github.com/alexzhang13/rlm/blob/main/docs/architecture.md) provides comprehensive setup and architectural guidance.
- The `RLMLogger` system enables full execution replay via the visualizer tool.

## Frequently Asked Questions

### Where can I find the RLM quick-start tutorial?

The primary quick-start tutorial is located at [`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py) in the repository root. This script demonstrates basic client initialization and a single completion call. Comprehensive written instructions are also available in [`docs/getting-started.md`](https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md).

### Do I need Docker to run the RLM examples?

No, Docker is only required for the sandboxed examples. You can run [`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py), [`examples/lm_in_repl.py`](https://github.com/alexzhang13/rlm/blob/main/examples/lm_in_repl.py), and most other scripts using the `LocalREPL` environment, which executes code in your host process. Docker, Modal, and Prime sandboxes are optional for isolated execution.

### How do I visualize the execution traces from RLM?

Use the `RLMLogger` class as demonstrated in [`examples/logger_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/logger_example.py). Initialize it with `RLMLogger(log_dir="./logs")` to capture trajectories as JSONL files. Then navigate to the `visualizer/` directory and run `npm run dev` to launch the web interface for replaying execution graphs.

### Can I extend RLM with custom functions for the model to call?

Yes, the [`examples/custom_tools_example.py`](https://github.com/alexzhang13/rlm/blob/main/examples/custom_tools_example.py) file demonstrates how to register user-defined functions that become available as tools within the REPL environment. These functions are injected alongside standard globals like `llm_query` and `rlm_query`, allowing the model to invoke your domain-specific logic during execution.