Agent configuration reference
The agent reads the same keys from four places. Highest precedence first:
- Managed configuration, deployed by a fleet tool and not overridable by the user:
macOS, the
ai.metermark.agentpreference domain (the per-user payload under/Library/Managed Preferences/<user>/over the computer-level one); Windows,HKLM\SOFTWARE\Policies\MetermarkoverHKCU\SOFTWARE\Policies\Metermark; Linux,/etc/metermark/config.jsonover$XDG_CONFIG_HOME/metermark/config.json. - Environment variables.
config.jsonin the agent's data directory, written bymetermark setup.- Defaults.
metermark status lists every managed value under Configuration with the file or registry key
it came from.
| Key (managed / config.json) | Environment variable | Default | Meaning |
|---|---|---|---|
endpoint | METERMARK_ENDPOINT | https://metermark.ai | the hosted API |
enrollment_key | METERMARK_API_KEY | — | an enrollment key (mm_enroll_…, from Settings → Machines; upload and classify only) for fleet installs, or an API key. metermark setup --api-key … stores it in config.json. Self-installs use the sign-in token instead. |
user_email | METERMARK_USER_EMAIL | the signed-in account, else the tool's login | who the sessions belong to. From a profile or the environment it is the fleet's answer and wins; in config.json it is the account setup recorded. See Who the sessions belong to. |
sync_interval_minutes | METERMARK_SYNC_INTERVAL | 15 | the schedule; 0 pauses the machine (the schedule still ticks, the agent exits at once) |
content_mode | METERMARK_CONTENT | samples | samples: short prompt excerpts go to the classifier in memory; metadata: no prompt text leaves the machine, sessions are counted and costed but not labeled |
collectors | METERMARK_COLLECTORS | all | which local tools to read: claude-code-local, codex-local, cursor-local, cursor-cli-local |
update_channel | METERMARK_UPDATE_CHANNEL | stable | stable: the agent replaces itself with a verified release, checked at most once a day; managed: never, the fleet tool owns the version |
identity_map | — | — | the content of an identity.json file, { "people": [ { "canonical": "…", "emails": ["…"], "team": "…" } ] }, as a dictionary or a JSON string: aliases → the person's email |
log_level | METERMARK_LOG | info | error, info or debug; prompt content is never logged at any level |
data_dir | METERMARK_HOME | ~/.metermark (%LOCALAPPDATA%\Metermark on Windows) | where the local store, credentials, config, state and a self-install's bin live |
classify_since | — | written by setup | on the free plan, only sessions started at or after this time are labeled, so the month's labels go to new work; plans without a cap ignore it and label the backlog too |
Windows registry
The managed keys above as values under HKLM\SOFTWARE\Policies\Metermark (machine policy; wins)
or HKCU\SOFTWARE\Policies\Metermark (user policy), read at the start of every run:
| Value | Type | Example data |
|---|---|---|
endpoint | REG_SZ | https://metermark.ai |
enrollment_key | REG_SZ | mm_enroll_… |
user_email | REG_SZ | drew@corp.example |
sync_interval_minutes | REG_DWORD | 15 (0 pauses the machine) |
content_mode | REG_SZ | samples or metadata |
collectors | REG_MULTI_SZ (or a comma-separated REG_SZ) | claude-code-local, cursor-local, codex-local |
update_channel | REG_SZ | managed or stable |
log_level | REG_SZ | info |
identity_map | REG_SZ | the identity.json content as a JSON string |
Anything else under the key is ignored; a value of the wrong type is ignored, never fatal.
Linux configuration files
The managed keys above as a JSON object in /etc/metermark/config.json (machine policy; wins) and
$XDG_CONFIG_HOME/metermark/config.json (~/.config/metermark/config.json by default), read at
the start of every run. Types are the JSON ones: strings, a number for sync_interval_minutes, an
array of strings (or a comma-separated string) for collectors, an object (or a JSON string) for
identity_map.
{
"endpoint": "https://metermark.ai",
"enrollment_key": "mm_enroll_…",
"user_email": "drew@corp.example",
"sync_interval_minutes": 15,
"content_mode": "samples",
"collectors": ["claude-code-local", "codex-local", "cursor-local"],
"update_channel": "managed",
"log_level": "info"
}
Unknown keys, wrong types, and a file that is not a JSON object are ignored, never fatal.
Files the agent owns
Per user (on Windows, every ~/.metermark/… path is %LOCALAPPDATA%\Metermark\…):
| Path | Contents |
|---|---|
~/.metermark/metermark.db | sessions, labels, usage days (numbers and short labels, no prompt text) and the tool logins folded into the person |
~/.metermark/credentials.json | the refresh token (self-install only), readable only by the user |
~/.metermark/config.json | the user-level settings above |
~/.metermark/identity.json | optional: the same shape as identity_map, for a person with several logins |
~/.metermark/state.json | the last run: when, exit code, counts, whether it was idle, last update check, the plan as last reported |
~/Library/Logs/Metermark/agent.log (macOS) · ~/.metermark/logs/agent.log (Linux) · %LOCALAPPDATA%\Metermark\logs\agent.log (Windows) | rotated log, 4 MB × 3, never any prompt content |
~/Library/LaunchAgents/ai.metermark.agent.plist · ~/.config/systemd/user/metermark-agent.{service,timer} · Task Scheduler entry \Metermark Agent | the schedule (self-install) |
A fleet install owns /Applications/Metermark.app, /Library/LaunchAgents/ai.metermark.agent.plist
and /usr/local/bin/metermark on macOS, and %ProgramFiles%\Metermark\metermark.exe plus the
Active Setup entry on Windows; the per-user files above are the same. The managed configuration
files and registry keys are read, never written, by the agent.
Exit codes of metermark run
0 ok (including "nothing new, no requests") · 2 not signed in, or no terminal for the browser
sign-in · 3 endpoint unreachable (the schedule retries) · 4 quota reached (labeling paused,
everything still synced) · 5 credential revoked or expired (sign in again).
Releases
https://metermark.ai/download/manifest.json lists the current version with, per asset, its URL,
SHA-256 and size: darwin-arm64, darwin-x64, linux-x64, windows-x64 (the binaries the
installers use), darwin-app (the signed and notarized macOS app), darwin-pkg
(Metermark-<version>.pkg) and windows-msi (Metermark-<version>.msi). The same files are
served as /download/metermark-<platform>, /download/Metermark.app.zip, /download/Metermark.pkg
and /download/Metermark.msi, each with a .sha256 beside it; add ?version=<version> to pin one.
metermark update reads the manifest, downloads the asset for its platform, verifies the checksum
and size, and replaces the program in place.