Configuration

Atlas is designed to work with minimal configuration. Settings control filesystem event debouncing and agent audit logging.

Config File

Atlas reads configuration from ~/.atlas/config.toml. This file is optional — if it doesn’t exist, defaults are used.

View the current configuration:

atlas config
atlas config --json    # Machine-readable output

Output:

Config file: ~/.atlas/config.toml
Status: present
Database: ~/.atlas/atlas.db

Effective settings:
  debounce_ms: 1000
  audit_cli: false

Settings

debounce_ms

How long Atlas waits (in milliseconds) after seeing a file change before processing it. This prevents Atlas from reacting to intermediate states during rapid saves.

Default: 1000

debounce_ms = 1000

Lower values make Atlas more responsive but may cause duplicate processing during multi-step save operations. Higher values are more conservative but add latency before changes appear in history.

Rename and Remove events always bypass debounce for immediate processing.

audit_cli

Whether CLI --json calls are logged to the agent audit table. When enabled, any command invoked with --json is recorded in the same agent_audit_log table used by the MCP server, with source = "cli".

Default: false

audit_cli = true

See Atlas Connect for details on the audit log and MCP server.

[connect.scope]

Controls which watched paths are visible to agents through Connect. Scope filtering operates at the query boundary — agents see no indication that filtered data exists.

allow — List of path prefixes. If any entries exist, agents can only see entities under these paths.

deny — List of paths or glob patterns. These are always hidden from agents, even if under an allowed prefix. Deny wins over allow.

Default: On first run, Atlas seeds deny entries for ~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gh, **/credentials*, **/.env, and **/secrets*.

[connect.scope]
allow = ["/Users/you/Projects"]
deny = [
    "~/.ssh",
    "**/credentials*",
    "**/.env",
]

Manage scope rules with atlas connect scope. See Connect Scope for full details.

Data Directory

Atlas stores all data in ~/.atlas/. This directory is created automatically on first run.

~/.atlas/
  atlas.db          # SQLite database
  atlas.db-wal      # Write-ahead log (auto-managed)
  atlas.db-shm      # Shared memory (auto-managed)
  atlas.pid          # Daemon PID (while running)
  atlas.log          # Daemon log output
  connect.pid        # MCP HTTP server PID (while running)
  connect.log        # MCP HTTP server log output
  config.toml        # Configuration (optional)
  .consent           # First-run consent marker

The database file is created with 0600 permissions (owner read/write only).

Shell Completions

Generate tab completions for your shell:

# Bash
atlas completions bash > ~/.bash_completion.d/atlas

# Zsh
atlas completions zsh > ~/.zsh/completions/_atlas

# Fish
atlas completions fish > ~/.local/share/fish/vendor_completions.d/atlas.fish

Restart your shell or source the file to activate.