Skip to main content

Toolchain Proxies

Toolchain proxies expose a configured toolchain command under its normal command name. Atmos resolves the proxy, installs its pinned tool on first use, and forwards the command arguments.

Coreutils ls​

The uutils release provides a coreutils multicall binary. Define an ls proxy to run it as coreutils ls while continuing to type ls:

atmos.yaml
toolchain:
  aliases:
    coreutils: uutils/coreutils
  proxies:
    ls:
      tool: coreutils
      args: [ls]
.tool-versions
coreutils 0.9.0

Activate proxies in an interactive shell, then use the command normally:

eval "$(atmos toolchain env)"
ls stacks/

Atmos creates ls in ${toolchain.install_path}/bin/proxy. That link invokes Atmos again under the name ls; Atmos reads the proxy configuration, resolves coreutils through toolchain.aliases, installs the pinned version when absent, and runs coreutils ls stacks/.

Configuration​

toolchain.proxies is a map from command name to a tool and optional prefix arguments:

toolchain:
  proxies:
    my-command:
      tool: owner/repository-or-alias
      args: [subcommand, default-flag]
  • tool is required and follows normal tool alias resolution.
  • args are optional and are inserted before arguments supplied to the proxy.
  • The first version for the alias or canonical owner/repository in .tool-versions is used.
  • Proxies run a package's primary registry binary. Use prefix arguments for multicall tools such as coreutils.

Proxy names must be safe command basenames. Atmos will not overwrite a non-link or a link it did not create for the current executable.

Where Proxies Work​

Atmos prepares the proxy environment for built-in command runners, custom commands, workflows, component commands, and hooks. A shell step can therefore run ls without manually exporting a path when its parent command declares the proxy.

For commands you run directly in your terminal, opt in with atmos toolchain env. The generated Bash, Fish, PowerShell, dotenv, and JSON output includes the proxy path and the private context that keeps a proxy associated with the configuration that created it after cd into another directory.

Platform Behavior​

On Unix-like systems, Atmos creates symbolic links to its executable. On Windows, it creates executable hard links so proxy activation does not require the symlink privilege; invoke the proxy by its normal command name and Windows resolves the .exe link.

Scope and Troubleshooting​

Proxies do not replace system commands globally. They are found only by Atmos child processes or shells that place the proxy directory first in PATH.

If a proxy cannot resolve its tool, ensure its alias is valid and .tool-versions contains a pinned version. If a proxy link cannot be created, remove or rename the conflicting user-managed file rather than allowing Atmos to replace it.