Language behavior

Runtime selection

Languages and startup owns interpreter requirements and selection. Package settings owns package defaults and preparation policies. Language visibility changes tool fields, not the availability of a SQL provider. Tool discovery is independent of server readiness.

R

R cells run in persistent global state with native console behavior. Every visible top-level expression can autoprint. The whole cell is parsed before evaluation, so a parse error runs none of it. Evaluation or print errors preserve earlier effects and normally leave the worker usable.

R owns its normal startup files and workspace restoration; see Native R startup. Console supplies transport, interrupt, graphics, and documentation output integration. R event handlers, including later callbacks, can run while idle and produce output collected by a later call.

Use ordinary package-loading operations. In managed implicit mode, reached missing-package loads can prepare dependencies without rerunning the cell. A sandboxed R worker also has a temporary writable library; manual installations there last only for that worker and remain subject to permissions.

text <- capture.output(print(?stats::lm))
writeLines(text[80:120])

Python

Python cells execute in persistent __main__.__dict__; the final expression is displayed. The whole cell is compiled before execution. Ordinary exceptions print a traceback and leave the worker usable. An uncaught main-thread SystemExit terminates the worker.

Console supplies r and _console.sql_connection() through Python’s builtins; attaching reticulate may also bind r in __main__. Alongside Python’s standard workspace metadata and builtins, these are the intentional conveniences available without imports. Console’s internal imports, setup state, and exception helpers remain private. Modules such as os, sys, and tempfile enter the workspace only when user code or startup hooks bind them. Later setup and interrupt recovery preserve those user bindings; restart creates a fresh workspace.

Startup hooks run before cells, and attaching reticulate later preserves the running interpreter and its objects. The working-directory import entry follows os.chdir(). Managed implicit mode can resolve reached missing imports; existing environments require preinstalled packages.

Console does not provide a notebook event loop. Manage asynchronous work explicitly. Background threads and subprocesses can produce raw output, but managed dependency resolution is restricted to the owning interpreter thread. Prepare packages before starting such work.

R and Python interoperability

Reticulate supplies the bridge; see the language guide for data-transfer examples.

Python globals are available from R through py$name. Attribute access attaches the bridge on demand; loading reticulate or reading its py proxy alone need not initialize it. Conversion follows reticulate’s rules. Objects and proxies do not survive worker replacement.

Console attaches four R helpers in tools:mcp-console:

These aliases preserve reticulate’s arguments, return values, and conversion rules. Import, evaluation, and execution use Console’s shared Python interpreter and state. Installing or inspecting the helpers does not initialize Python, and ordinary R definitions can mask them.

For help, use help("import", package = "reticulate") for py_import(). The other helpers use their matching reticulate help topics, for example help("py_run_string", package = "reticulate").

py_require() without arguments returns the current R-side Python declarations. Under managed Python’s explicit and implicit policies, evaluated declarations authorize preparation, including calls from R package .onLoad() hooks. Pre-initialization declarations are accepted when Python is prepared; MCP requirements inspection returns the last committed declaration. Before Python initializes, action = "set" can replace requirements; after initialization, compatible additions preserve live objects. Use restart for changes that require a fresh environment.

Ordinary Python does not need to attach reticulate, and R can run without Python.

SQL and DuckDB

Managed SQL uses one in-memory DuckDB connection and persistent catalog. R owns the default through DBI when available; otherwise Python owns it through DB-API. No setup cell is required. Missing optional providers can be prepared on demand in managed sessions. A user-selected connection can provide SQL without DuckDB.

Console supports DuckDB 1.x and 2.x. The default package request is bare duckdb, so the selected R or Python package resolver chooses the release; Console does not pin a major version.

With R-owned DuckDB, unqualified names can refer to R global data frames; a table or view with the same name takes precedence. Views can observe later rebinding of an R name. To query a Python frame through this provider, first assign it to an R global.

With Python-owned DuckDB, register frames explicitly:

_console.sql_connection().register("measurements", frame)

Here frame is an existing Python data frame. Python globals are not automatically scanned into the SQL catalog. DuckDB CLI dot commands are not supported. Use read-only attachment for databases outside writable sandbox paths.

import sqlite3

connection = sqlite3.connect(":memory:")
_console.sql_connection(connection)

connection <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
.console$sql_connection(connection)

first <- .console$sql_last_result(n = 100)
rest <- .console$sql_last_result()

first = _console.sql_last_result(n=100)
rest = _console.sql_last_result()

Plots and images

R’s managed device returns PNG pages and finalizes open pages at cell end, including after language errors. A later cell cannot add layers to a finalized plot. Defaults are 800 × 600 pixels at 96 DPI. Set persistent dimensions in inches and resolution:

options(
  console.plot.width_in = 16,
  console.plot.height_in = 10.5,
  console.plot.dpi = 100
)

Explicit user devices are neither closed nor captured. This includes devices that reuse a closed managed device’s number and filename template. Native R startup happens before the managed device attaches, so its plots use R’s native device.

Python captures open pyplot figures at cell end, including after an exception, and then closes them. plt.show() captures immediately and closes figures; calling it is optional. plt.pause() captures frames while keeping figures open. savefig() does not suppress capture, but closing an unshown figure does. Figures outside pyplot are not captured.

An inherited MPLBACKEND is respected; otherwise Console uses Agg. Matplotlib configuration can be read from the host. Cache writes use private storage in sandbox.tempdir: managed; other modes retain normal library cache selection. These plot rules also apply across the reticulate bridge.

Output and notices

Language warnings and errors are ordinary console output. Preparation, transport, and protocol failures are MCP tool errors. MCP results defines status notices and Calls and session lifetime defines readiness, replacement, and polling behavior. Output limits and Recording reference describe previews, raw logs, and retention.

Current limitations

There are no named sessions or parallel cells. Recordings are not checkpoints and Console provides no file-read/search tool. No aggregate retention quota or automatic cleanup is implemented.

Initialize R before starting background threads that access the native process environment; concurrent native environment access during R startup is unsupported. Partial runtime initialization can require restart.

Platform enforcement and descendant cleanup have explicit sandbox limits. Open work distinguishes unresolved engineering items from deliberately unsupported features.