Environment Variables¶

The variables the backend reads, grouped by what they switch. Values entered under Customizations in the web studio are saved to settings.json in the state directory and take effect without a restart; an environment variable set at start applies to the whole process. Every default below is the value the code uses when the variable is unset.

Provider keys¶

Model routing¶

A routing value whose provider has no key is skipped with a warning, and the Customizations page shows the model the role resolves to instead.

Decision model¶

State, paths, and access¶

Toolchain¶

Seqera, Wave, and the nf-core pin¶

CODARIS_ACTION_GATE=0 also waives the approval card for a registry push, and nothing else about it: the registry list and the Dockerfile switch still apply.

What the agent's shell can see. A command the agent runs (run_command, the builder's nf-core and nextflow calls, a pipeline it launches on the local executor, a fix command) starts with the backend's environment after secrets are removed from the environment of every shell-out: names ending _API_KEY or _TOKEN, or containing SECRET, PASSWORD or CREDENTIAL, access and private keys, the AWS credential variables, CODARIS_WAVE_APPROVAL_KEY, TOWER_ACCESS_TOKEN, database, mail and cache passwords (*_PASS, PASS), AUTHORIZATION, KEY, NETRC, the *ASKPASS helpers, *CONNECTION_STRING* and *SAS_URL*, and any value that is a credential whatever the variable is called: one that carries user:password@ in a URL (a credentialed proxy), a connection string or SAS URL (AccountKey=, sig=), a password= pair, a bearer token, or a token with a well-known prefix (sk-, ghp_, xox). PATH, HOME, LANG, TMPDIR, DOCKER_HOST, NXF_*, JAVA_*, CONDA_* and the non-secret CODARIS_* settings are kept. A command that names TOWER_ACCESS_TOKEN, wave.seqera.io, mcp.seqera.io or a process's environment (/proc/<pid>/environ, ps eww) is refused, with a message pointing at build_container_image and the Seqera tools. The registry host under it, community.wave.seqera.io, where those builds' images live, is not one of them: docker pull, singularity pull, grep and nextflow run on such an image reference are not refused.

Credential files. run_command and the file tools also refuse to read or write files that hold credentials, wherever they are, with a message that names the rule: .env and .env.* (but not the template .env.example), *.pem, *.key, id_rsa*, id_ed25519*, .netrc, .nextflow/secrets/*, and everything in or under .ssh, .aws, .kube and .docker (so .aws/credentials, .docker/config.json and .kube/config among the rest). The shell's environment is scrubbed, but a file on the disk is not an environment variable, and CODARIS_ALLOWED_DIRS includes your home directory by default. A command is judged the way the state files below are, and conservatively where it cannot tell: a bare name such as entry.key in a script counts only when that file exists, but not when the command walks trees (find, grep -r, rg, fd, locate, rsync, tar, cp -r, ls -R), or has a cd it cannot resolve or a cd with a glob, and a name it writes by redirection (> .env) counts whether or not the file is there yet. A command that reads whole trees fails closed: every token is checked for a walker (find, rg, ag, ack, fd, locate, rsync, tar, zip, tree, du, grep/cp/ls/chmod/chown/scp with a recursive option in any cluster or long form, python -m tarfile|zipfile|shutil), wherever it sits in a wrapper (env, nice, timeout, sudo, stdbuf, ionice, chrt, busybox, xargs), and the command is refused when any of its path words, or the directory it runs in, is at or above $HOME or $CODARIS_HOME, is inside or above $NXF_HOME/secrets, the directory of $AWS_SHARED_CREDENTIALS_FILE or of a file in $KUBECONFIG (when set), is in .nextflow (it holds secrets/), or holds a variable the gate cannot expand, or when xargs hands it paths it cannot see, or it takes its paths from a file (--files-from, --files0-from, tar -T); the value of a directory option is judged as a path in every spelling (tar -C dir, -Cdir, --directory=dir, cp -t dir, -rtdir, --target-directory=dir), and python -m tarfile|zipfile|shutil is found after any interpreter options (-u, -W ignore, -mtarfile). There is no walk of the disk to look for credentials, so a recursive read of a folder below your home that holds a .env is not caught by name, and this is best effort. a path with a variable it cannot expand is judged with the variable left out (~/.s${X}sh/id_rsa); a hard link to a credential file is recognised by its inode; and code that builds its paths at run time (an interpreter, $(...), a backtick) is refused when it holds a fragment of a credential name (.env, id_rsa, .ssh, .aws, .kube, .docker, .netrc, secrets, credentials, .pem, .key). If a pipeline really needs one of these, give the agent a non-secret copy or a path to the value outside these rules. All of this reads what a command says, and the sandbox is the real control. An OS-level sandbox (the toolchain container without the credentials mounted, or a separate UID that cannot read them) is the only complete enforcement; a program that computes a path from data the gate cannot see gets past a gate that reads text.

The state directory is an allowed root, so the agent could once write mcp_servers.json there and, on the next reload, have the registry send a token to a URL it chose. mcp_servers.json, settings.json (the provider keys), notifications.json (who is emailed), permissions*, grants* and the chat and ledger database codaris.db with its -wal, -shm and -journal files (the capability grants are a table in it) directly under CODARIS_HOME are therefore protected files, and so is a notification file named by CODARIS_NOTIFY_SETTINGS. run_command and the file tools refuse any command or path that names one, however it is spelled (.., an absolute path, ~, $CODARIS_HOME, quotes and escapes inside the path, $'...', braces, a glob, a symlink or a hard link), with no card. The command is first normalised into plain words: $'...' and $"..." are decoded, quotes and escapes removed, heredoc bodies and every quoted command line inside it (bash -c "...") read again, each cd and pushd tracked in order. A command that is not a plain look at the disk (ls, cat, grep, find without -exec, every word resolvable) is then refused when it can write and cannot be shown to leave the state files alone: it names the state directory itself as a destination or runs in it (cp x $CODARIS_HOME/, mv, rsync, install, ln, tar -C); it names the state directory together with a state file's name; it names the state directory and builds part of a path with $(...), a backtick, $'...' or an escape such as \x41; it changes directory more than once into the state directory or somewhere it cannot work out; it creates a link (ln, cp -s) while naming a path in the state directory; or it cannot be read as shell words. Where it cannot tell what a variable or a cd means it refuses rather than guesses: a word with a variable it cannot expand and a state file's name ($X/settings.json), a cd into a directory it cannot name followed by a state file's name, quoting nested more than three levels deep, and a command with more than 20,000 distinct words (write a large file with the file tool). $PWD and $OLDPWD are the directory the command is in at that point. sessions/, logs/ and the chat's own workspace are not affected. Only the operator endpoints (the add and remove calls, with their one-time code from the log) and the CLI write these files. This gate reads what a command says, so it is defence in depth, not a sandbox: a program that builds a path at run time, or a script written in one step and run in the next, is not caught. The robust protection is to keep the agent's commands out of the state directory's reach: set CODARIS_TOOLCHAIN_CONTAINER=1 so its shell-outs run in the toolchain container, which does not mount it, or run the backend under a different UID from the commands and keep the state files private to it (CODARIS_ALLOWED_DIRS does not cover a command that names a path outright). A server entry may name only the variables in CODARIS_MCP_HEADER_VARS, and the secret store no longer falls back to the environment for a name it did not capture at start-up.

The built-in MCP server is started with none of its secrets in its environment, and no tool call can give it any: the backend makes a pipe for that one child, starts it with the read end inherited and --provision-fd <n> on its command line (a number, not a secret), writes one line holding the Perplexity key, the Platform token and the approval key, and closes it. The child reads the line once, before it serves a request, closes the pipe and keeps the values in memory, so ps eww on it shows nothing and there is no tool a model could call to replace them. A built-in server that Codaris started and that did not receive them refuses Wave builds. A built-in server started by something else (another harness, a script) uses its own environment, which its owner chose.

The Seqera token is not left in the backend's own process environment either. At start-up the backend moves TOWER_ACCESS_TOKEN, WAVE_API_TOKEN and every variable a server's headers_env names into memory, removes them from os.environ so no child inherits them, and overwrites the strings exec left in the process's environment block with zeros, which is what ps -E (macOS) and /proc/<pid>/environ (Linux) read. Deleting the variable alone does not do that: the string stays in the block, and ps -E printed it after a del os.environ[...] in the check made for this change.

Which process holds the container's environment. A process's startup environment stays readable in /proc/<pid>/environ for as long as it runs, and a process that spawns the backend keeps its own copy. In the all-in-one image, docker/entrypoint.sh used to stay PID 1 as bash and start uvicorn as its child, so /proc/1/environ held the token for the life of the container, and unset in bash does not change what that file prints. Now the entrypoint starts the frontend, with an environment without the secrets (env -u for the Seqera and Wave tokens, PERPLEXITY_API_KEY, the approval key, every CODARIS_WAVE_* variable, and the variables listed in CODARIS_MCP_HEADER_VARS both as written and in upper case, never PATH, HOME and the like), and a watcher that ends the container if the frontend dies, and then execs the backend. The backend is PID 1: nothing is left whose environment holds the secrets, and the backend overwrites its own copy as described above. The registry's start-up takes the same names out of the backend (the Seqera and Wave tokens, PERPLEXITY_API_KEY, CODARIS_WAVE_APPROVAL_KEY, the Seqera header variables and everything in CODARIS_MCP_HEADER_VARS, whether or not a server uses it); the other CODARIS_WAVE_* variables are settings, not credentials, so the backend keeps them and only the services started before it lose them. Two consequences. The backend, as PID 1, does not reap orphaned grandchildren (a background process the agent leaves behind stays a zombie until the container restarts). And do not run the image with docker run --init or Compose init: true: the init process becomes PID 1, is started with the container's whole environment, and nothing overwrites it. The separate backend image runs uvicorn directly as PID 1 and has the same property. Outside Docker, nothing starts the backend from a shell script, but a shell that does (TOWER_ACCESS_TOKEN=... uvicorn ...) leaves that shell's own copy for as long as it lives.

--reload is for development without real tokens. uvicorn --reload (used by docker/docker-compose.dev.yml) runs a reloader process that starts the server as its child. The reloader holds the environment it was started with, including TOWER_ACCESS_TOKEN, for as long as it runs, and the backend's overwrite cannot reach it, so the agent's shell can read the token from the reloader's /proc/<pid>/environ (or ps -E). Use --reload only with throwaway or no tokens.

PERPLEXITY_API_KEY is held in memory too, and for the same reason: the built-in server receives it on the pipe, so the backend's own copy only made it readable. At start-up it is moved into the store and out of the environment, and the research client, the Perplexity router, the model resolver and the Customizations page read it from there (a key saved on that page goes straight into the store). What remains in the backend's environment is everything else you started it with, including the other provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY and the rest). Moving those into the same store is a follow-up and is not part of this change. On Linux the backend and the built-in child also call prctl(PR_SET_DUMPABLE, 0) at start-up, so another process of the same user cannot read their /proc/<pid>/environ or descriptors, and the gate above refuses a command that names /proc/<pid>/environ or ps eww. Those are defence in depth, not a sandbox: they do nothing on macOS and do not stop root. The robust fix is to keep the agent's commands out of the backend's reach: set CODARIS_TOOLCHAIN_CONTAINER=1, so its shell-outs run in the toolchain container, which never had the backend's environment, or run the backend under a different UID from the commands.¶

Build and agent behaviour¶

Server and logging¶

Variables not listed here are internal switches for subgraphs and experiments; the authoritative list is grep -rho 'CODARIS_[A-Z0-9_]*' backend/app | sort -u.