Configuration

Argent reads its settings from four places: configuration keys, feature flags, secrets and environment variables. This page lists all of them.

Configuration keys

A configuration key is a named value with a fixed schema. Argent recognizes a fixed set of keys. You cannot add your own key.

Commands

Command	Description
argent config list	Show every key with its effective value and its source
argent config list --json	Print the same list as JSON
argent config get <key>	Print the effective value of one key
argent config get <key> --scope <s>	Print the value stored at one scope
argent config set <key> <value>	Write a value
argent config unset <key>	Remove a value at one scope

Add --scope project to set or unset to change the key for the current project only. The default scope is global.

argent config set recordings.directory ~/Movies/argent
argent config set lens.agent codex --scope project
argent config get ios.additionalDeviceSets

Available keys

Key	Scopes	Merge	Description
telemetry.enabled	project, global	restrictive wins	Whether anonymous telemetry is on. Default true. Read-only here: use argent telemetry (with --scope project for the project file)
allowlist.enabled	project, global	restrictive wins	Set to false to keep argent update from re-applying editor auto-approve allowlist rules. Unset keeps the refresh
lens.agent	project, global	project wins	The coding agent that argent lens starts without the picker, for example claude or codex
ios.additionalDeviceSets	project, global	union	Additional CoreSimulator device-set directories. Argent lists the simulators in these sets next to the default set. An array of paths
android.sdkRoot	project, global	project wins	The Android SDK root that Argent uses instead of ANDROID_HOME, in the tool-server and in the simulator-server. Absolute or ~/-prefixed. adb on PATH still wins
android.adbServerPort	project, global	project wins	The adb server port that Argent uses instead of 5037, from 1 to 65535. The tool-server reads it only when it starts. Restart the tool-server with argent server stop after a change. ANDROID_ADB_SERVER_PORT or ADB_SERVER_SOCKET still wins
recordings.directory	project, global	project wins	The directory where Argent saves a finished screen recording. Default .argent/recordings under the project root
scripts.maxTimeoutMs	global	global wins	The largest time limit, in milliseconds, that an e2e script step can ask for. Default 300000, which is five minutes. Argent refuses a value below 100
scripts.heapLimitMb	global	global wins	The heap limit, in MiB, that Argent gives to each e2e script process. Default 512. Argent refuses a value below 32

Argent reads scripts.maxTimeoutMs and scripts.heapLimitMb from the global file only. A project file cannot raise the limits that one script step runs under.

A path value is absolute, starts with ~, or is relative. For ios.additionalDeviceSets, Argent resolves a relative entry against the scope that set it: the project root for the project file, the home directory for the global file.

allowlist.enabled only affects argent update. When it is false, an update leaves editor auto-approve allowlists entirely alone — rules already written stay, and argent init still asks its auto-approve question as before. When the key is unset (the default), nothing changes: update keeps refreshing the rules for editors that already have Argent configured. false in either scope wins, so a committed project file opts out a whole team.

Argent resolves recordings.directory on the client host, the machine that receives the mp4. A relative value always resolves against the project root, or the home directory when there is no project, regardless of which file set the value.

android.adbServerPort does not change the adb server of the agent's own shell. When Argent uses an adb server other than the default, the result of list-devices shows the agent how to reach that server. The agent puts the environment variables from that result before each adb command that it runs itself.

Storage

Argent stores the keys as JSON in two files:

Scope	Path
Global	~/.argent/config.json
Project	<project-root>/.argent/config.json

The two files share the shape of the key. ios.additionalDeviceSets lives at { "ios": { "additionalDeviceSets": [...] } }.

Argent reads both files at each request. Thus a change takes effect immediately. android.adbServerPort is the exception: the tool-server reads that key only when it starts. The merge column above decides the effective value when both files set the same key:

Merge	Result
project wins	The project value replaces the global value
union	The global entries come first, then the project entries, without duplicates
restrictive wins	The more restrictive value wins. false in either file turns telemetry off
global wins	The global value replaces the project value

Argent finds the project root at the nearest parent directory that contains .argent, .git or package.json. The feature flags below use the same two directories and the same project root.

Feature flags

A feature flag is a boolean switch. Each flag turns one behavior of Argent on or off. Argent recognizes a fixed set of flags. You cannot add your own flag.

Commands

Command	Description
argent flags	List the flags with their description and state
argent flags --json	Print the same list as JSON
argent enable <name>	Turn a flag on
argent disable <name>	Turn a flag off

Add --scope project to enable or disable to change the flag for the current project only. The default scope is global.

argent enable argent-lens                    # global
argent enable argent-lens --scope project    # this project only

Available flags

Flag	Default	Description
argent-lens	Off	Enable Argent Lens: the propose_variant and await_user_selection tools, the preview window, and the argent lens command
disable-auto-screenshot	Off	Stop the automatic screenshot that Argent captures after each interaction tool
disable-auto-describe	Off	Stop the accessibility element tree that Argent appends after each interaction tool
artifacts-list-endpoint	Off	Expose the GET /artifacts endpoint of the tool-server for remote artifact consumers
tool-server-event-log	Off	Write the lifecycle events of the tool-server to a JSONL file
boot-sound	Off	Default the sound argument of boot-device to true, so Android emulators boot with audio output instead of muted
microinteractions	Off	Animate the host window to match device actions. Cosmetic only, macOS only
harmonyos	Off	Enable HarmonyOS support: list, boot and drive HarmonyOS phones and DevEco Studio emulators over hdc
forward-secrets	Off	Send the secrets of the client to a linked tool-server. See Secrets over a link
video-watermark	On	Put the Argent watermark in the corner of a recorded screen video

The tool-server writes the event log to ~/.argent/tool-server-events.jsonl. Set the ARGENT_EVENT_LOG environment variable to select a different path.

Storage

Argent stores the flags as JSON in two files:

Scope	Path
Global	~/.argent/flags.json
Project	<project-root>/.argent/flags.json

Argent reads the project file first, then the global file. Thus a value in the project file replaces the value in the global file. If neither file contains the flag, Argent uses the default of the flag.

To turn a globally enabled flag off in one project only, write the value in the project file:

{
  "flags": {
    "argent-lens": false
  }
}

Effect of a change

Argent reads the flag files at each request. Thus argent enable and argent disable take effect immediately. You do not restart the tool-server.

A tool that a flag controls is available to the agent only while the flag is on. If the flag is off, the tool is absent from the tool list and the agent cannot call it.

Removed flags

Argent can remove a flag from the recognized set. argent flags shows a flag that is still in your files but no longer recognized in a separate section. Run argent disable <name> to remove such an entry.

Secrets

An e2e step or a keyboard call can type a credential without the credential in the file or in the agent context. The step contains a placeholder:

- type: { into: { id: password }, text: "{{secret:APP_PASSWORD}}" }

The tool-server replaces the placeholder when the step runs. The tool-server resolves the name on the machine that runs the tool-server. It takes the first source that defines the name:

Order	Source	Accepted keys
1	Environment variable ARGENT_SECRET_<NAME>	Prefixed variables only
2	<project-root>/.argent/secrets.env	Every key. Add this file to .gitignore
3	<project-root>/.env.local, then <project-root>/.env	Keys with the ARGENT_SECRET_ prefix only
4	~/.argent/secrets.env	Every key, for every project

A bare NAME=value line in .env or .env.local stays unresolved. Write ARGENT_SECRET_NAME=value in these files.

A change in a secrets file applies to the next tool call. An environment variable reaches only a tool-server that started after you exported the variable.

A name that no source defines fails the step at run time. Argent redacts each resolved value in the reports and logs. Thus do not use a placeholder for content that a report must show.

Secrets over a link

With argent link or ARGENT_TOOLS_URL, the tool-server can run on a different computer, for example a hosted Mac. By default, that computer must define each secret. Enable the forward-secrets flag to use the secrets of the client instead:

argent enable forward-secrets

With the flag on, the client does these steps for each call to a linked tool-server:

1. The client finds each {{secret:NAME}} placeholder in the call. This includes the e2e test file, its run: fragments and its nested e2e tests.
2. The client resolves each name with the sources in the table above, on the client computer. The client finds the project root from its own working directory.
3. The client sends each value that it finds with the call, in the x-argent-client-secrets request header.

The tool-server uses these values before its own sources. The tool-server resolves a name that the client does not define with its own sources. When neither the client nor the tool-server defines a name, the error says that the client did not provide the secret. Define the secret on the client computer. The tool-server does not store the values. A value that paste pastes stays on the clipboard of the device, as for a secret of the tool-server.

The client sends a value only for a name that the call contains. The client reads the flag on the client computer. A tool-server that is older than this feature ignores the values and uses only its own sources.

The flag gives the linked tool-server each secret that a call names. A call of any tool can name any secret of the client, so enable the flag only for a tool-server that you trust with all of these secrets.

The header contains the values as plain text. Thus the client sends the values only to an https:// URL or to a loopback address, for example an SSH tunnel to 127.0.0.1. The client does not send a call that names a secret of the client over plain HTTP to a different computer, and the call fails. When NODE_TLS_REJECT_UNAUTHORIZED is 0 on the client, the client does not check the certificate of an https:// URL. Thus the client also does not send these values over https://, and the call fails. To trust a self-signed certificate, set NODE_EXTRA_CA_CERTS instead. When a link is set, argent enable forward-secrets and argent secrets tell you whether the client can send values to it.

A tunnel or a proxy can store the request headers. For example, the local web inspector of ngrok records each request with its headers. Turn off this recording for a link that forwards secrets.

The tool-server accepts 16 KiB of request headers in total. Thus one call can send approximately 11 KiB of secret values. The client does not send a call whose request headers would be more than 16 KiB, and the call fails. A proxy can have a lower limit. For example, nginx accepts 8 KiB for one header by default. When a proxy or the tool-server refuses the header as too large, the call fails. Define a secret of this size on the computer of the tool-server.

The client does not follow a redirect for a call that sends secret values, and the call fails.

Commands

Command	Description
argent secrets	List the names that a placeholder can resolve, and their sources
argent secrets list	Same as argent secrets
argent secrets --json	Print the same list as JSON

The command prints names only. It never prints a value. When two sources define the same name, the command marks the later copy as shadowed.

echo 'APP_PASSWORD=...' >> ~/.argent/secrets.env
argent secrets

Environment variables

An environment variable changes the behavior of the process that reads it. Export the variable before you start that process. Most variables apply to the tool-server. Restart the tool-server with argent server stop after a change.

Tool-server

Variable	Default	Description
ARGENT_PORT	3001	The port the tool-server listens on
ARGENT_HOST	127.0.0.1	The address the tool-server binds to
ARGENT_IDLE_TIMEOUT_MINUTES	0	Minutes without a request after which the tool-server exits. 0 disables the timeout
ARGENT_EVENT_LOG	~/.argent/tool-server-events.jsonl	Path of the event log that the tool-server-event-log flag writes
ARGENT_SCREENSHOT_SCALE	0.25	Scale factor of a captured screenshot, between 0.01 and 1. A smaller value returns a smaller image. The 0.25 default applies to iOS and Android phones and tablets. When the variable is unset, Argent downscales a screenshot of a local Apple TV simulator, an Android TV or Vega to at most 576 pixels on its long side. An Android TV whose form factor or display size cannot be read in time keeps 0.25. Chromium ignores the variable. The scale parameter of screenshot overrides it.
ARGENT_CHROMIUM_PORTS	empty	Comma-separated CDP ports that Argent probes for Chromium apps, in addition to 9222
ARGENT_CHROMIUM_PORTS_FILE	~/.argent/chromium-cdp-ports.json	Path of the file that remembers the CDP ports of apps that Argent started

Devices

Variable	Default	Description
ARGENT_SIMULATOR_NO_WINDOW	unset	Set 1, true or yes to boot an iOS simulator without the Simulator window
ARGENT_EMULATOR_NO_WINDOW	unset	Set 1 to boot an Android emulator without a window, for CI, containers or Wayland-only sessions
ARGENT_EMULATOR_GPU_MODE	auto on macOS, swiftshader on Linux	The value of the emulator -gpu option, for example host
ARGENT_EMULATOR_GUEST_VULKAN	unset	Set 1, true or yes to boot Android emulators on macOS with guest Vulkan when the guestVulkan argument of boot-device is not set. By default, Argent boots them with -feature -Vulkan, because guest Vulkan crashes the GPU process of Chrome. Without guest Vulkan, apps find no Vulkan device, and WebGPU content does not show
ARGENT_IOS_TEAM_ID	unset	The Apple Developer Team ID that signs the runner for physical iOS devices. Unset, Argent detects the team from the keychain of the Mac. The variable must be in the environment of the tool-server; a value in the shell of the client does not reach a running server
ANDROID_HOME, ANDROID_SDK_ROOT, ANDROID_AVD_HOME	SDK defaults	The standard Android SDK locations. Argent reads them to find adb, the emulator and the AVDs

MCP server

Variable	Default	Description
ARGENT_TOOLS_URL	unset	URL of the tool-server that the MCP server and the CLI use. Takes precedence over argent link
ARGENT_AUTH_TOKEN	unset	The token that the MCP server and the CLI send to the tool-server that ARGENT_TOOLS_URL names. argent server start prints the token in the argent link string. A tool-server that argent server start --no-auth starts needs no token only when the shell of that command does not export this variable. Unset the variable before you run argent server start --no-auth
ARGENT_MCP_LOG	~/.argent/mcp-calls.log	Path of the log of tool calls that the MCP server writes
ARGENT_AUTO_SCREENSHOT_DELAY_MS	per tool, 1400 otherwise	Minimum milliseconds between an interaction tool and its automatic screenshot. Raises the per-tool default; it cannot lower it. See the disable-auto-screenshot flag
ARGENT_TOOL_SERVER_SHUTDOWN_ON_MCP_EXIT	unset	Set 1 to stop the tool-server when the editor closes the MCP server
ARGENT_E2E_FILES_LOG	unset	Set 1 to make the MCP server and the CLI print one stderr line for each run: fragment, nested e2e test, snapshot baseline and tool: file argument that they send over a link, before the call. This includes the files of a step that the agent records. The MCP server or the CLI also prints one line for each baseline that it writes after the call. Each line holds the path and the result: inline or upload with the size in bytes, listed, missing, written, or refused with the reason. It never holds the content. ARGENT_FLOW_FILES_LOG is the old name and still works

Telemetry

Variable	Description
DO_NOT_TRACK	Set 1 to turn telemetry off for this process. argent telemetry status shows the result

See Telemetry and privacy for the opt-out command and the committed project opt-out.