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 |
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 a flow 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 flow 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.
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. 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 |
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
A flow 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.
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. |
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_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_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 |
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.