Skip to main content

Languages and startup

Choose an R installation or Python environment, control native R startup, and select a SQL connection before analysis begins. Sessions and languages introduces the shared session. Package settings covers startup packages and preparation policies; Tool settings controls which languages the model can use.

Put these settings in a configuration file. Relative interpreter paths use Console’s launch directory, including when written in a global file; a leading ~ follows the shared path rules. Settings are captured when the server starts. Open a new server connection to change them; restarting the runtime does not reload YAML.

Limit concurrent sessions

Set sessions.max to limit live sessions on each MCP connection, including default:

sessions:
  max: 4

The value must be a positive integer or null. Omission and null mean unlimited; 1 allows only the default session. The default session reserves a slot for the connection’s lifetime, including when its startup fails. Starting named sessions count toward the limit, and a restart that starts a replacement worker retains the slot. A stopped named session releases its slot after worker cleanup, and can be started again when capacity is available. Preparing requirements in a stopped named session occupies a slot until preparation cleanup finishes. Calls that would exceed the limit fail without running their code; calls to existing live sessions remain available. See Named sessions for creation, polling, and stopping workers.

Choose a Python environment

Use an existing environment when you want to manage its packages yourself, or managed Python when you want Console to prepare the environment and packages.

The Python field reference lists selection forms and defaults.

Use an existing environment

python: .venv

Existing Python requires CPython 3.10 or newer with a usable shared embedding library. Console itself needs no third-party Python packages; the standard library is sufficient for standard-library code. Install the packages your analysis needs in the selected environment, such as pandas, Matplotlib, or duckdb for the Python-owned SQL connection. Console uses the environment as supplied and does not resolve or install its Python packages.

A virtual-environment directory must contain pyvenv.cfg and its ordinary bin/python or Windows Scripts/python.exe. You can also select the Python executable directly; executable paths preserve virtual-environment identity and symlinks. On Windows, select a real interpreter or virtual environment, not a Windows App Execution Alias. Recognized Conda installations are unsupported.

Existing selections accept no package, version, or resolution settings. An explicit selection overrides launch-time RETICULATE_PYTHON. A broken environment fails rather than falling back to another interpreter. The session’s filesystem and network permissions still apply.

Managed Python

python:
  version: ">=3.12,<3.14"

Use a quoted version or constraint string; see the Python field reference.

The same fields are accepted under python.managed and in a managed fallback candidate. For packages and resolution fields in these mappings, see Package settings.

Managed selection uses uv-managed CPython, rather than selecting a fallback interpreter on PATH. It excludes versions older than CPython 3.10 before ranking available versions or applying constraints. Without R, managed preparation requires uv on the execution host.

Flat and nested managed settings combine under the configuration merge rules; resolved output uses nested paths. Changing one selection form does not remove incompatible fields inherited from an earlier layer; clear the earlier branch before replacing it when necessary.

Try environments in order

python:
  first_available:
    - existing: .venv
    - active_venv
    - managed:
        version: "3.13"
Candidate Selection behavior
existing: PATH Use that executable or virtual environment when its path exists. An absent path advances to the next candidate; a present but unusable environment fails.
active_venv Use the incoming VIRTUAL_ENV. An unset or empty value advances to the next candidate; a supplied but unusable environment fails. The launcher must preserve this variable.
managed: {...} Use managed Python with the settings above. This candidate must be last.

Only absence advances to the next candidate; a broken selection does not. Exhausting the list is an error.

Choose an R installation

By default, Console discovers an installed R from installation hints and PATH. Select a particular installation with an executable path:

r: /opt/R/bin/R

The scalar form expands to r: {executable: PATH} before configuration layers are merged. Use a mapping to combine executable selection with startup settings:

r:
  executable: /opt/R/bin/R
  vanilla: true

The R field reference lists executable, package, and startup settings.

For r.packages and r.resolution, see Package settings.

Select an executable or launcher, not an R installation directory, Rscript, or a command with arguments. An explicit executable overrides installation hints and PATH discovery. The environment reference covers discovery variables such as R_HOME.

Console retains the selected installation across runtime restarts. If its captured executable or resources change incompatibly, start a new server connection. Executables and the code they load are trusted inputs; selecting them does not make them immutable sandbox assets.

Control R startup files

R uses normal native startup by default: environment files, profiles, workspace restoration, .First(), and default-package attachment are R’s responsibility. Startup has the session’s ordinary permissions. Console passes --quiet, --interactive, and --no-save, and does not save a workspace at shutdown.

To request R’s native --vanilla behavior:

r:
  vanilla: true

This affects the session’s R runtime. Runtime discovery and dependency preparation remain profile-free, so worker .Rprofile and .Renviron files do not configure the separate resolver. Use resolver environment settings for preparation credentials or mirrors. See R startup and libraries for the recognized native variables.

Console attaches its bridges and managed graphics after native startup, so startup plots use R’s native device. A profile diagnostic that R survives does not make the session unusable. If R fails initialization or is interrupted, fix the startup file externally and explicitly restart; ordinary calls do not retry initialization. Edits to .Rprofile take effect on runtime restart because R reads the file again, even though YAML configuration remains captured for the server connection.

Select a SQL connection at startup

Without a startup setting, SQL uses the session’s managed DuckDB connection. Use startup source to create and select a different connection before the first SQL cell:

startup:
  language: python
  code: |
    import sqlite3
    connection = sqlite3.connect(":memory:")
    _console.sql_connection(connection)

Both language and code are required; see the startup field reference.

For R, use language: r, create a normal DBI connection, and select it with .console$sql_connection(connection). Python uses a DB-API connection and _console.sql_connection(connection). The program must finish with a usable, user-created connection selected on that same interpreter. Retrieving or resetting the managed default does not satisfy startup.

Source runs after runtime helpers are available, once per worker, including after a restart. It is captured when the server launches; the encoded startup configuration, including escaping, is limited to 32 KiB. It is not automatically echoed as a submitted cell, but emitted output and errors are visible. Startup code has ordinary session permissions and can have side effects.

Failure or interruption withholds SQL until explicit restart. Console does not fall back to managed DuckDB or automatically replay failed startup source. Restart can repeat earlier side effects. After successful startup, resetting the connection restores managed DuckDB without rerunning the source. See SQL connections for connection ownership and reset behavior.