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 executionconsole_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.