Configuration files

Files and precedence

When Console starts, it reads configuration from these sources, in order:

You can use all three together. Console layers them in the order shown: later settings override matching earlier settings, while other settings stay in effect. Neither file is required.

See Merge rules for how nested settings combine, or Choose which files to load to select a different file or skip either location. To change the global file’s location, see Console home.

Create a configuration file

To create a project configuration, run this in your project directory:

mcp-console config init

This creates .agents/console/config.yaml. To create a global configuration shared across projects, run:

mcp-console config init --global

Both commands create a starter file with commented examples. The starter uses sandbox.profile: workspace, which allows ordinary project writes; see Sandbox permissions. See Initialization options to preview the file, choose another project directory, or customize the starter.

Inspect the combined settings

From the directory where your client starts Console, inspect the combined settings:

mcp-console config resolve

This uses the same files and command-line overrides as starting a session, without starting interpreters or preparing packages. Built-in defaults are omitted; add --full to include them. You can save the resolved configuration for a later session or edit its generated tool descriptions and parameter settings.

Use the Reference index to look up a configuration key.

Choose which files to load

Use these options to select or skip configuration files:

Launch defaults still apply before these files, and command-line overrides apply afterward. The options for skipping files cannot be combined with --config-file. Options may appear before or after the subcommand. They do not edit files or change recording-location selection.

Console looks for the project file only in the directory where it starts; it does not search parent directories. Missing automatic files are skipped, but an explicitly selected file must exist. Configuration must be a readable YAML or JSON mapping; invalid files and unknown fields are errors.

Configuration files can choose which programs Console runs, provide credentials, and change permissions. Console loads project files automatically, including when the client was registered globally. Review a project’s settings before launching Console; use --no-project-config to skip them for an unfamiliar project. A project file can grant permissions beyond those set in a global file or inherited from the client.

Settings are captured when the server starts. Restarting a worker does not reload configuration.

Command-line overrides

For serve and ordinary sandbox launches, settings are applied in this order:

1. Each --default-config KEY=VALUE assignment, in argument order.
2. Global $MCP_CONSOLE_HOME/config.yaml, or ~/.agents/console/config.yaml when the variable is unset.
3. Project .agents/console/config.yaml in the launch directory.
4. Each -c KEY=VALUE override, in argument order.

mcp-console serve -c 'sandbox.filesystem.read_write=[.]'
mcp-console serve --no-project-config -c 'python=.venv'
mcp-console serve --config-file ./session.yaml

Use --default-config KEY=VALUE to supply a preference that configuration files can override:

mcp-console serve --default-config sandbox.profile=inherit_codex
mcp-console config resolve --default-config sandbox.profile=inherit_codex

Both assignment options accept the same dotted keys and YAML values. Repeated assignments preserve order within their layer, including assignments before and after the subcommand. Files always take precedence over --default-config, and -c always takes precedence over files, regardless of argument placement. Explicit null and empty lists retain their normal replacement semantics; they are not treated as missing values.

Dotted keys address mappings, not list indexes. Values accept YAML strings, booleans, finite numbers, lists, objects, and null. Quote the assignment for the shell and quote strings that resemble numbers or booleans. To set a literal dotted environment name, supply its containing mapping:

mcp-console serve -c 'environment={"APP.VERSION": "v1", COUNT: "42"}'

There is no variable expansion or file inclusion in these values. -c accepts an assignment, not a file path or root configuration document.

Supply sandbox configuration through an environment variable

For standalone commands, sandbox --config-env NAME reads a YAML or JSON mapping from the named launch environment variable. It accepts the same structure as a configuration file, including sandbox, environment, and inherit_environment.

CONSOLE_CONFIG='sandbox: {profile: workspace, network: restricted}' \
  mcp-console sandbox --config-env CONSOLE_CONFIG -- python analysis.py

This replaces global and project file discovery. --default-config settings apply before the environment document, and ordered -c overrides apply after it. --writable-root adds launch-specific write access as usual. The selector cannot be combined with --config-file, --no-config, --no-global-config, or --no-project-config.

The variable must contain one configuration mapping; an unset variable, empty text, or invalid configuration fails before the command starts. Use {} to select Console’s defaults. Relative paths use the launch directory, and omitted settings retain their ordinary defaults, including managed temporary storage. The selected variable is removed from the command’s environment, and stdin remains available to the command. Environment and argument size limits still apply.

Runnable examples use child-specific environments in shell, Python, and R.

Merge rules

Mappings merge recursively. Lists, scalars, and null replace the earlier value. Validation and defaults apply to the final merged settings.

For example, global environment: {KEEP: global, CHANGE: global} and project environment: {CHANGE: project} retain KEEP and replace CHANGE.

To replace a whole mapping, clear it and then supply the replacement through ordered overrides:

mcp-console serve -c sandbox.network=null -c 'sandbox.network={proxy: {mode: limited}}'

The final value must still be valid for that setting. For example, sandbox.filesystem, sandbox.network.proxy, environment, and resolver require mappings rather than null. Changing one selector does not implicitly remove incompatible siblings.

Before merging each layer, Console expands an R path to r.executable and direct managed Python fields to python.managed. An empty python: {} also selects the managed form. Flat and nested runtime settings therefore merge at the same paths; Languages and startup describes the selection rules.

Export a configuration

To save the combined settings, including built-in defaults, and launch with that file:

mcp-console config resolve --full > session.yaml
# Review session.yaml, then launch with that file alone.
mcp-console serve --config-file session.yaml

config resolve uses the same file selection, ordered -c overrides, and validation as serve. It does not start interpreters, prepare packages, or create session/cache directories. Use --no-config to skip discovered files, --config-file PATH for one required file, and --format json for JSON instead of YAML. To inspect the built-in defaults without launch overrides, run mcp-console config resolve --no-config --full.

The default --prune omits values equal to the binary’s built-in defaults, independently of discovered files. The comparison uses defaults for the same sandbox choice as the export. An unchanged configuration produces {}. Mappings are pruned recursively. Changed arrays and scalar values stay complete, including empty arrays and strings; overrides needed to preserve conditional defaults remain explicit. --full includes defaults and generated tool descriptions; it cannot be combined with --prune.

Tool prose is pruned against generated text for the selected languages, permissions, and timeout visibility. Explicit text remains when those conditional defaults differ.

Use the same launch directory for export and execution so relative paths retain their meaning. For host execution, pass --no-sandbox to both commands; launch flags are not stored in YAML. Runtime-dependent interpreter selection, automatic package lists, inherited environment values, and runtime-created cache and temporary paths remain policies. Python first_available retains its candidates, including active_venv; the next launch evaluates them against its own environment and filesystem. Managed fallback entries include their effective resolution policy even when an existing candidate is selected. An export does not pin installed dependencies or copy the host environment. Exported interpreter paths must be representable as UTF-8.

Paths

Relative paths use the launch directory, including paths written in a global file. A leading ~ expands to the launching user’s home in interpreter selectors, cache.directory, sandbox and resolver filesystem paths, supported Unix-socket paths, configuration filenames, and --writable-root. MCP_CONSOLE_HOME also accepts a leading ~.

Expansion uses a nonempty, absolute HOME from the launch environment. On Windows, an absent or empty HOME uses USERPROFILE or native user-profile discovery. R_USER, MCP_CONSOLE_HOME, and child environment or resolver.environment overrides do not redefine that home. An invalid home is an error when expansion is needed.

Only ~, ~/..., and, on Windows, ~\... expand. Quote a standalone "~" in YAML, where an unquoted ~ means null. Use ./~/... to name a literal ~ directory. ~user, globs, and environment-variable references are not expanded. Expansion preserves symlinks and does not create directories. Settings expand after file and CLI layering; configuration filenames expand before reading. Materialized settings expose expanded home paths, including paths in Python candidate lists. Other strings, including environment values and startup programs, retain their contents.

Console home

Set MCP_CONSOLE_HOME in the launching environment to a directory to relocate global configuration and fallback session storage. It does not relocate package caches, change HOME, or override project-local recording selection. The directory must be absolute after leading-~ expansion; empty or relative values are errors when it is needed.

Without it, Console uses an absolute HOME. On Windows, an absent or empty HOME uses USERPROFILE or native user-home discovery. See Recordings for project-local storage.

Generated configuration

With no overrides, config init generates this config.yaml:

## MCP Console configuration, shared across clients.
## Full reference:
## https://posit-dev.github.io/mcp-console/reference/#configuration
##
## Reconnect your client after editing.
## Relative paths use Console's launch directory, not this file's directory.
## Omitted settings inherit global configuration, then Console defaults.
## Lines beginning with ## explain settings; lines beginning with # can be uncommented.

sandbox:
  ## The workspace profile allows creating, editing, and deleting project files.
  ## The workspace is Console's launch directory.
  ## Changing the working directory later does not change the workspace.
  ## .git, .agents, .codex, .aws, and .claude stay read-only, even when absent.
  ## .agents includes this configuration file; referenced Git metadata is protected too.
  ## Other host files remain readable when permitted by the OS.
  ## Network access and temporary storage are configured separately below.
  ## Use read_only instead to omit the profile's workspace write grants.
  profile: workspace

  ## Add exceptions to the selected profile's filesystem permissions.
  ## To grant writes only to selected directories, use profile: read_only first.
  # filesystem:
  #   read_write: [/absolute/path/to/shared-output]
  #   read_only: [./reference-data]
  #   deny: [./.env, ./secrets]

  ## Temporary storage options:
  ## - managed (default): private writable storage with Console cleanup.
  ## - read_write: writable host temp directories, without Console cleanup.
  ## - read_only: no private storage or automatic temporary write grants;
  ##   other filesystem permissions still apply.
  ##   Note: R will not work without a writeable temporary directory.
  # tempdir: managed

  ## Network options: restricted (default), enabled, or a proxy mapping.
  ## enabled allows network access.
  ## Use a proxy to allow selected hosts.
  ## Use hostnames, not URLs; quote wildcard patterns.
  ## Package downloads use separate permissions.
  # network:
  #   proxy:
  #     domains:
  #       allow: [api.example.com, "*.example.org"]

  ## Allow code to start local servers, e.g. http://localhost:8000,
  ## and use loopback network connections.
  ## auto (default): false where possible on Unix, true on Windows.
  ## false is unsupported on Windows when a proxy is enabled.
  #   allow_local_binding: true

## Package preparation policies for R and managed Python:
## R defaults to implicit; managed Python defaults to explicit.
## implicit: startup packages, explicit requests, and missing loads/imports.
## explicit: startup packages and explicit requests only.
## fixed: prepare startup packages; reject later package changes.
##
## Supplied package lists replace the default startup lists.
## [] requests no optional startup packages; it does not disable preparation.

## R packages to prepare at startup.
## To disable R preparation, set resolution: disabled and packages: [].
## Required R infrastructure must then already be installed.
# r:
#   resolution: implicit
#   packages: [dplyr, ggplot2]

## Let Console manage Python and prepare these initial packages.
## version accepts a quoted version or constraint; omit it for no constraint.
# python:
#   version: "3.13"
#   resolution: explicit
#   packages: [numpy, pandas, matplotlib]

## Alternatively, use an existing Python environment without managing its packages.
## Choose this instead of the managed Python settings above.
## The environment and its required packages must already be installed.
# python: .venv

## Environment variables for evaluated code and package preparation.
## Values must be strings.
# environment:
#   OMP_NUM_THREADS: "4"

## Cache options: managed (default when sandboxed), host, or a directory mapping.
## Use host to reuse ordinary host package caches.
## directory places managed dependency caches under <directory>/dependencies.
## Relative directories use the launch directory; a leading ~/ uses your home.
## It applies to package preparation and workers.
## Configuration and recordings stay in their existing locations.
# cache:
#   directory: /absolute/path/to/console-cache