Skip to contents

Make a ConsoleConfig, edit it if needed, then pass it to console_tools(). There are two ways to make the configuration: supply settings directly with ConsoleConfig(), or load selected files with load_console_config(). Both return the same editable S7 class. Examples are displayed without execution. For a complete analysis task, see Giving an agent an R session.

Supply settings in R

ConsoleConfig() accepts named fields or one named list, without combining the two forms. Its arguments after ... must use their full names; a single list may be passed in the first position. Nested lists follow the structure of config.yaml and become typed, validated properties. The constructor reads no files, discovers no runtimes, and starts no processes.

config <- ConsoleConfig(
  r = list(packages = c("dplyr", "ggplot2"), resolution = "fixed"),
  python = list(managed = list(version = "3.13", packages = "pandas")),
  sandbox = list(
    filesystem = list(read_write = "./output", deny = "./secrets"),
    network = "api.example.com"
  ),
  resolver = list(environment = list(UV_INDEX_URL = "https://pypi.org/simple"))
)

tools <- console_tools(config, project = "/path/to/project")

The calling R installation is the default at loading and launch time. Use ConsoleConfig(r = list(executable = "/opt/R/bin/R")) to select another installation. An executable selected in a file or supplied object takes precedence over that default. ConsoleConfig() itself does not fill in an executable.

Select an existing Python environment with python = ".venv" or python = list(existing = ".venv"). It must already exist; Console does not install packages into it. Managed Python accepts version, packages, and resolution, either inside managed or directly in the Python mapping. R and managed Python support these package preparation policies:

resolution At startup During the session
"implicit" Prepare the declared packages. Also prepare missing packages on supported loads/imports or explicit requests. This is the R default.
"explicit" Prepare the declared packages. Prepare additional packages only on explicit requests. This is the managed Python default.
"fixed" Prepare the declared packages. Reject changes to the package declaration.
"disabled" (R only) Use installed packages, including Console’s R dependencies. No managed package preparation. packages must be omitted or empty.

Omitting packages keeps Console’s default startup packages; packages = character() requests no optional packages. Existing Python environments use their installed packages and accept no packages, version, or resolution settings. These policies control Console’s package preparation, not arbitrary installation commands in submitted code.

project must be an existing directory. It sets the child’s working directory without changing the caller’s directory. All relative configuration paths use it, including paths written in a global file.

Select languages and runtimes

Use R lists for nested settings, character vectors for lists of strings, and TRUE or FALSE for booleans. NULL omits a field from a newly constructed object; empty vectors and mappings are retained. The ConsoleConfig reference lists all fields and their accepted values.

To expose only R and SQL, use installed R packages, and limit the connection to one session:

config <- ConsoleConfig(
  languages = c("r", "sql"),
  r = list(resolution = "disabled", vanilla = TRUE),
  sessions = list(max = 1)
)

To try an existing Python environment and otherwise prepare a managed one:

config <- ConsoleConfig(
  python = list(
    first_available = list(
      list(existing = ".venv"),
      "active_venv",
      list(managed = list(version = "3.13", packages = "pandas"))
    )
  )
)

An absent environment advances to the next choice; an existing but unusable environment fails. Only one "active_venv" and one managed choice are allowed.

To select a database connection before the first SQL cell:

config <- ConsoleConfig(
  r = list(packages = c("DBI", "RSQLite")),
  startup = list(
    language = "r",
    code = paste(
      'connection <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")',
      ".console$sql_connection(connection)",
      sep = "\n"
    )
  )
)

Startup code must leave a user-created connection selected on the chosen interpreter. If it fails, SQL remains unavailable until an explicit restart; Console does not silently use its default DuckDB connection.

Read one YAML file yourself

Use yaml12 to parse a file, then pass its mapping to the constructor:

settings <- yaml12::read_yaml("config.yaml")
config <- ConsoleConfig(settings)
# Equivalently:
config <- do.call(ConsoleConfig, settings)

tools <- console_tools(config = config, project = "/path/to/project")

Neither construction nor launch discovers additional files. Quote Python versions and environment values in YAML so they remain strings.

Load global and project settings once

load_console_config() reads the selected sources, applies optional R overrides, validates them with Console, and returns a ConsoleConfig. It does not start interpreters or prepare packages.

project <- "/path/to/project"
config <- load_console_config(project = project)
print(config)
tools <- console_tools(config, project = project)

The default sources are:

Argument Default source
global_file $MCP_CONSOLE_HOME/config.yaml, or ~/.agents/console/config.yaml when that variable is unset
project_file file.path(project, ".agents", "console", "config.yaml")

There is no ancestor-directory search. Changing project changes the default project file too. An explicitly supplied relative project_file, such as "settings/report.yaml", is also interpreted under project. A missing default file is skipped; an existing malformed or unreadable file fails. A non-NULL path supplied explicitly must exist, even if it spells the conventional path. Set a source to NULL to disable it:

load_console_config(global_file = NULL) # Project only
load_console_config(project_file = NULL) # Global only
load_console_config(global_file = NULL, project_file = "settings/report.yaml")

Settings apply in this order: built-in defaults and the calling R preference, global file, project file, then overrides. In a selected file, r: null or r.executable: null clears the calling R preference and leaves R discovery to Console, including after edits and at launch. Exporting with jsonlite::write_json(as.list(config), "config.json", auto_unbox = TRUE) retains that reset as r.executable: null; reloading the file with load_console_config() preserves native discovery. overrides can be a named list or a ConsoleConfig:

config <- load_console_config(
  overrides = list(
    r = list(packages = c("rmarkdown", "httr2")),
    inherit_environment = FALSE
  ),
  project = "/path/to/report"
)

Mappings normally merge recursively; arrays and scalars replace earlier values. An explicitly supplied worker sandbox policy, resolver sandbox policy, or Python selection replaces that entire inherited node. For example, overrides = list(sandbox = list(filesystem = list(read_write = "./reports"))) replaces an inherited worker policy, including its network grants. An override such as sandbox = list(network = NULL) omits the network field but still replaces the inherited policy, just like sandbox = list(). Omitted fields do not act as overrides. An empty package vector means no optional startup packages.

File discovery ends when the loader returns. Editing a source file or changing MCP_CONSOLE_HOME afterward does not change that object’s settings or cause another file read at launch or worker restart. Use the same project, and the same Console path or version, when loading and launching. project is a working directory for those operations, not a field stored in the configuration object. During development, use a matching checkout binary.

Environment variables and file selection

MCP_CONSOLE_HOME changes the default global source and fallback recording directory, not the project file or package caches. An explicit global_file bypasses it; global_file = NULL disables global loading.

A leading ~ uses Console’s launch-home convention: an absolute HOME, with Windows user-profile fallback when HOME is absent or empty. It is independent of R’s R_USER and path.expand(). An empty or relative MCP_CONSOLE_HOME is invalid when the default global source is used. $VARIABLE and ${VARIABLE} strings inside configuration are not interpolated.

Child environment settings are separate from source discovery:

config <- ConsoleConfig(
  inherit_environment = FALSE,
  environment = list(TZ = "UTC"),
  resolver = list(environment = list(UV_INDEX_URL = "https://pypi.org/simple"))
)

By default, workers and preparation processes inherit the launch environment. Shared environment values override inherited values; resolver.environment adds overrides for preparation. Console supplies its own runtime variables afterward. inherit_environment = FALSE controls child inheritance, while the launcher still uses its host environment for its own work. Setting MCP_CONSOLE_HOME inside environment does not move the files the loader reads. A loaded config captures file settings, not a snapshot of inherited environment variables or a package lock. See environment variables for runtime selection and other controls.

Inspect and edit configuration

Use print(config) to review settings, @ for typed properties, and $ for named parameter entries. Nested properties also accept lists when replacing a section:

config@sandbox <- list(
  filesystem = list(read_write = "./reports"),
  network = "api.example.com"
)
config@tool <- list(parameters = list(timeout_ms = list(enabled = FALSE)))

For appending to an existing vector, a small local replacement function avoids repeating the path:

`append<-` <- function(x, value) c(x, value)
append(config@sandbox@filesystem@read_write) <- "./figures"
append(config@sandbox@network@proxy@domains@allow) <- "data.example.com"

Create the parent sections first, as above. This helper belongs to the script; it is not another Console API.

Generated tool descriptions remain owned by Console and reflect the current settings when launching. An explicit description remains an override, including an empty string:

config@tool <- list(
  description = "Run one R report cell.",
  parameters = list(timeout_ms = list(enabled = FALSE))
)

The loader retains authored tool fields; generated descriptions and schemas are not copied into the object. schema is read-only metadata; argument types and constraints cannot be changed.

Permissions

Choose a base profile, then add filesystem and network rules as needed:

sandbox$profile Behavior
"read_only" (default) Read host files and write private temporary storage. No ordinary project writes or worker networking. This does not hide readable host secrets.
"workspace" Also allow ordinary writes under project, while protecting workspace metadata such as .git and .agents. Network access remains separate.
"inherit_codex" Use the launching client’s permissions when available; otherwise use the read-only base. This applies only to workers.
list(inherit_codex = list(fallback = "workspace")) Use client permissions when available, with workspace writes as the fallback. "read_only" is the other fallback value.

For an ellmer chat with project writes, "workspace" selects the policy directly:

config <- ConsoleConfig(sandbox = list(profile = "workspace"))
tools <- console_tools(config, project = "/path/to/project")

The workspace profile declines automatic writes when project is a filesystem root, the home directory, or an ancestor of home. Explicit filesystem rules can add or restrict access within either base profile.

Keep filesystem and network rules under their respective sections:

config <- ConsoleConfig(
  sandbox = list(
    filesystem = list(
      read_only = "./data",
      read_write = "./output",
      deny = "~/.ssh"
    ),
    network = list(
      proxy = list(
        domains = list(allow = "*.example.com", deny = "blocked.example.com")
      )
    )
  )
)

Workers have a host-read baseline, so read_only = "./data" does not hide other host files. Create output directories before launch. Filesystem deny wins at an identical path; more specific paths override broader grants, subject to platform limits. Proxy domain deny wins over matching allow; unmatched destinations are denied. Use network = TRUE (or "enabled") for direct networking and network = FALSE (or "restricted") to deny ordinary direct network access. A character vector or unnamed list of allowed patterns, such as network = c("api.example.com", "*.example.org"), becomes network.proxy.domains.allow. The scalar strings "enabled" and "restricted" are reserved mode names; any other single string is one allowed pattern. An empty vector or list() selects an explicit empty allow list. YAML accepts the same forms when read through either constructor. For a literal destination named enabled or restricted, use proxy.domains.allow explicitly. R network = NULL omits the field; YAML network: null preserves an earlier network value when files merge.

A named network mapping keeps the canonical config.yaml structure shown above and enables a managed proxy. Proxy options stay under proxy; sockets and allow_local_binding control local networking. Omitting proxy.domains retains context defaults. Supplying it selects explicit destination rules; an empty domains mapping or allow list can remove the resolver’s generated repository allowlist.

Use tempdir = "managed" for private temporary writes (the default), "read_write" for shared host temporary writes, or "read_only" for no temporary write grant. Exact proxy, socket, and platform-specific settings are in Sandbox permissions. Worker and resolver permissions are independent; see Package settings for package preparation. ConsoleConfig(sandbox = FALSE) disables both sandboxes and runs with host permissions.

Launch a configured session

console_tools() # Load the conventional files once, then launch
console_tools(config = config) # Use this object; discover no config files
console_tools(config = ConsoleConfig()) # Defaults without config files
console_tools(config = ConsoleConfig(sandbox = FALSE)) # Host execution

console_tools() returns all advertised tools in a named list for chat$register_tools(). Explicit config = NULL is equivalent to ConsoleConfig(). sandbox = FALSE disables worker and preparation enforcement; it cannot accompany an explicit resolver policy. Keep the tools reachable while the chat uses them. See ?ConsoleConfig, ?load_console_config, and ?console_tools for the three public entry points.