Configuration

Start with the settings UI

Run /settings in an interactive session or autohand --settings from a shell for common UI, agent, session, permission, network, telemetry, auto-mode, team, and search settings. Edit the config file directly for provider blocks, hooks, MCP servers, custom themes, extension providers, and advanced policy.

autohand --setup
autohand --settings
autohand config set ui.promptSuggestions false
autohand config set sessions.awareness coordinate
autohand --permissions

Configuration files and lookup

Autohand selects one user configuration source in this order:

1. An explicit --config <path>
2. The AUTOHAND_CONFIG environment variable
3. $AUTOHAND_HOME/config.toml
4. $AUTOHAND_HOME/config.yaml
5. $AUTOHAND_HOME/config.yml
6. $AUTOHAND_HOME/config.json

AUTOHAND_HOME defaults to ~/.autohand. Keep only one of the four standard config files in that directory; multiple formats are rejected instead of being merged. JSON is created with safe defaults on first run when no file exists.

Project-local overlay

When a workspace is known, Autohand also reads .autohand/settings.local.json. The overlay supports provider, model, agent, network, telemetry, and permissions. Those values override or merge with the user config for that workspace.

{
  "version": 1,
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4",
  "agent": {
    "maxIterations": 80
  },
  "permissions": {
    "allowList": ["run_command:npm test", "run_command:npm run lint"],
    "denyList": ["run_command:npm publish"]
  }
}

Keep this file local when it contains personal approvals. Project-scoped extensions, agents, skills, hooks, and MCP servers have their own documented storage and lifecycle; do not place arbitrary top-level user config inside this overlay.

Effective precedence

Explicit CLI flags control the current process. For persistent settings, the project overlay is merged over the selected user config, then supported environment variables override API and provider fields. A feature-specific runtime flag such as --no-idle-logout, --offline, or --no-browser applies last for that run.

Complete working example

This example shows the main current sections without embedding real credentials. Remove sections you do not use and provide secrets through your normal local secret-management process.

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "replace-locally",
    "model": "anthropic/claude-sonnet-4",
    "contextWindow": 200000
  },
  "workspace": {
    "defaultRoot": "/work/projects",
    "allowDangerousOps": false
  },
  "ui": {
    "theme": "dark",
    "silentToolOutput": false,
    "showThinking": true,
    "completionReportEnabled": true,
    "promptSuggestions": true,
    "activityVerbs": ["Indexing", "Reviewing", "Testing"],
    "activityVerbsEnabled": true,
    "activitySymbol": "✳",
    "statusLine": {
      "showProviderModel": true,
      "showContext": true,
      "showWorkspacePath": true,
      "showGitBranch": true,
      "showCommandHint": true,
      "showPullRequest": true,
      "showSessionLines": false,
      "showQueue": true,
      "showActiveStatus": true,
      "showActiveMetrics": true,
      "showCancelHint": true
    }
  },
  "agent": {
    "maxIterations": 100,
    "enableRequestQueue": true,
    "idleLogoutEnabled": true,
    "idleTimeoutMs": 3600000,
    "sessionRetryLimit": 3,
    "sessionRetryDelay": 1000,
    "parallelToolConcurrency": 5,
    "toolSelectionCache": true,
    "autoMemory": true,
    "debug": false
  },
  "sessions": {
    "awareness": "warn"
  },
  "permissions": {
    "mode": "interactive",
    "allowList": ["run_command:git status --short"],
    "denyList": ["run_command:npm publish"],
    "rememberSession": true
  },
  "features": {
    "usageV2": false,
    "tokenUsageStatus": false,
    "slashGoal": false
  },
  "teams": {
    "enabled": true,
    "teammateMode": "auto",
    "maxTeammates": 5
  },
  "search": {
    "provider": "browser-profile"
  },
  "mcp": {
    "enabled": true,
    "servers": []
  },
  "hooks": {
    "enabled": true,
    "hooks": []
  },
  "telemetry": {
    "enabled": false
  },
  "autoReport": {
    "enabled": true
  },
  "sync": {
    "enabled": true,
    "interval": 300000,
    "exclude": [],
    "includeTelemetry": false,
    "includeFeedback": false
  }
}

Top-level keys

Provider settings

Set the top-level provider to the provider Autohand should use. Common provider fields are model, apiKey, baseUrl, port, contextWindow, and reasoningEffort. Provider-specific integrations add fields such as Azure deployment/authentication data, Vertex project and region, xAI OAuth state, NVIDIA chat-template options, or Bedrock region and API mode.

Custom OpenAI-compatible providers

{
  "provider": "custom:company-gateway",
  "customProviders": {
    "company-gateway": {
      "id": "company-gateway",
      "displayName": "Company Gateway",
      "apiFormat": "openai-compatible",
      "baseUrl": "https://models.example.com/v1",
      "apiKey": "replace-locally",
      "apiKeyRequired": true,
      "model": "company-code",
      "contextWindow": 131072,
      "models": [
        {
          "id": "company-code",
          "label": "Company Code",
          "contextWindow": 131072,
          "reasoningEffort": "high"
        }
      ]
    }
  }
}

The object key and its id must match. apiFormat is currently openai-compatible. Set disabled to hide the provider without deleting its saved settings.

Trusted extension providers

{
  "provider": "extension:company-release",
  "extensionProviders": {
    "extension:company-release": {
      "model": "release-model",
      "apiKey": "replace-locally",
      "baseUrl": "https://models.example.com"
    }
  }
}

The extension controls additional fields, but every provider entry requires a non-empty model. The matching extension must be installed, enabled, trusted, and successfully activated. See Extension API v1.

UI settings

Status line

Every ui.statusLine field defaults to true except showSessionLines, which defaults to false.

Use /statusline for the interactive editor.

Agent and concurrent-session settings

{
  "agent": {
    "autoMemory": true,
    "idleLogoutEnabled": true,
    "idleTimeoutMs": 7200000
  },
  "sessions": {
    "awareness": "coordinate"
  }
}

Use --no-idle-logout for one long-running process without changing the saved config. Run autohand agents --once to print the live local agent/session snapshot.

Permission settings

Autohand's immutable security checks run before configurable policy. Configuration can narrow or approve supported actions, but it cannot override the immutable blacklist.

{
  "permissions": {
    "mode": "interactive",
    "allowList": [
      "run_command:git status --short",
      "run_command:npm test"
    ],
    "denyList": [
      "run_command:npm publish"
    ],
    "rules": [
      {
        "tool": "run_command",
        "pattern": "git diff *",
        "action": "allow"
      }
    ],
    "rememberSession": true
  }
}

Use /permissions or autohand --permissions to inspect the effective user, project, and session policy. Saved “always” decisions may be written to user or project scope; keep project-local approvals reviewable.

Features and experiments

Use autohand experiments list or /experiments to see the effective feature state. Local flags persist to their config path. Eligible server-controlled flags may be turned off locally through features.remoteOverrides, but a local config cannot force on a server-disabled remote flag.

autohand experiments list
autohand experiments status token_usage_status
autohand experiments enable token_usage_status
autohand experiments disable token_usage_status
autohand experiments refresh

Autohand inference rollout flag

features.autohand_inference separately gates the Autohand Cloud/local provider, setup choices, model discovery, RPC, and ACP surfaces. It is off unless deliberately enabled in config or with AUTOHAND_FEATURE_AUTOHAND_INFERENCE=1 (also accepted in AUTOHAND_FEATURES).

Auto-mode and teams

Local peer communication

Communication is independent of sessions.awareness and defaults off. Enable it to address other local sessions and published workers with the : composer or peer tools. Peer communication uses local Unix-domain sockets on macOS/Linux and requires no TCP or UDP port. See Required Ports and Agent Transports for agent IPC, local model servers, browser integration, and optional HTTP listeners.

{
  "sessions": {
    "communication": {
      "enabled": true,
      "scope": "workspace",
      "idleBehavior": "notify",
      "alias": "builder"
    }
  }
}

Use /peers list workspace, /peers list repository, or /peers list machine to choose a directory. The listing includes your own ID for controller setup. /peers send, /peers inbox, /peers reply, and /peers status expose delivery without requiring the user to relay model-to-model messages. Leading :peer message sends immediately; an inline selected :peer supplies an exact reference to the local model.

See the user guide, resource coordination, the technical reference, and the two-session lab. The Unix IPC adapter is implemented for macOS/Linux. Windows communication remains unavailable until private pipe and process-job adapters are implemented; keep communication disabled there. Changing auto-confirmation never bypasses an enabled resource policy.

Required ports and agent transports

Autohand Code has no single required inbound TCP port. Normal cloud inference uses outbound HTTPS, usually TCP 443. Local agent communication does not open a TCP listener. Additional ports depend on the provider and optional features you enable. The network settings above control retries and timeouts; they do not configure a listener, peer port, or firewall rule.

Peer communication across sessions and profiles

Peers communicate on the same machine, under the same OS user. The workspace, repository, and machine scopes control which local peers can discover and address each other; machine does not enable LAN or cross-host communication. No router forwarding, public inbound rule, or reserved TCP port is required for peers.

Profiles using different AUTOHAND_HOME directories must set the same sessions.communication.coordinationDirectory to discover one another. Each profile retains its private inbox in its own home. The runtime requires a private local directory and access to its Unix sockets; a shared network folder or opened firewall port does not create cross-host peer support. Windows peer communication is currently unavailable.

Choosing ports and diagnosing conflicts

For a local provider, an explicit baseUrl takes precedence over the provider's port. Change the server's listening port and the matching CLI URL together. For example, after starting Ollama on port 11435, use:

{
  "provider": "ollama",
  "ollama": {
    "baseUrl": "http://127.0.0.1:11435",
    "model": "your-installed-model"
  },
  "sessions": {
    "communication": {
      "enabled": true,
      "scope": "workspace"
    }
  }
}

For a predictable review URL, run autohand review serve --port 4173. If that port is occupied, choose another or use --port 0. Local providers that default to 8080 need distinct ports when running as separate servers at the same time. Optional local listeners should remain reachable only where you intend to use them.

On macOS/Linux, lsof -nP -iTCP:11434 -sTCP:LISTEN identifies the process listening on a model port; substitute the port you are diagnosing. For peer failures, use /peers list and check communication enablement, scope, the shared coordination directory, and socket permissions instead of opening a TCP port. Project dev servers, hooks, external tools, and third-party MCP servers can need additional ports defined by those programs. --offline suppresses startup network refreshes; it is not a firewall and does not force a cloud provider or tool to run locally.

Network, search, telemetry, and reporting

--offline disables startup network operations such as model-catalog and feature/announcement refreshes while preserving useful cached local state.

MCP and hooks

MCP servers

{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "repository-tools",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@company/repository-mcp"],
        "env": {
          "LOG_LEVEL": "warn"
        },
        "autoConnect": true
      },
      {
        "name": "remote-tools",
        "transport": "http",
        "url": "https://mcp.example.com/mcp",
        "headers": {
          "Authorization": "Bearer replace-locally"
        },
        "autoConnect": true
      }
    ]
  }
}

A server requires name and transport. stdio requires command; http and sse require url. Optional fields are args, env, headers, and autoConnect. Manage servers with autohand mcp or /mcp. See MCP servers.

Lifecycle hooks

{
  "hooks": {
    "enabled": true,
    "hooks": [
      {
        "event": "post-tool",
        "command": "./scripts/record-tool-result.sh",
        "description": "Record completed tool calls",
        "enabled": true,
        "timeout": 5000,
        "async": false,
        "filter": {
          "tool": ["run_command"]
        }
      }
    ]
  }
}

Each definition requires event and command. It may also set description, enabled, timeout, async, matcher, and a tool/path filter. Current events cover tool, prompt, response, file, session, permission, notification, sub-agent, auto-mode, auto-research, learning, goals, teams, review, mode, and context lifecycles. See Hooks and events for the event payload and control-flow contract.

Authentication, community skills, sharing, and sync

{
  "communitySkills": {
    "enabled": true,
    "showSuggestionsOnStartup": true,
    "autoBackup": true
  },
  "share": {
    "enabled": false
  },
  "sync": {
    "enabled": true,
    "interval": 300000,
    "exclude": ["temp/*"],
    "includeTelemetry": false,
    "includeFeedback": false
  },
  "externalAgents": {
    "enabled": true,
    "paths": ["/work/shared-agents"]
  }
}

Sync handles canonical memory event logs by event id instead of overwriting one device's history with another. Derived memory caches and locks are not synced. Sensitive config fields are encrypted for account sync, but you should still avoid committing secrets to a repository.

Browser integration

The historical config object remains chrome for compatibility. The public CLI and slash-command surface is browser-neutral: --browser, --no-browser, and /browser. The older --chrome aliases remain hidden compatibility inputs.

{
  "chrome": {
    "extensionId": "installed-extension-id",
    "browser": "auto",
    "userDataDir": "/path/to/browser/user-data",
    "profileDirectory": "Default",
    "installUrl": "https://autohand.ai/chrome",
    "enabledByDefault": false
  }
}

Environment variables

Runtime-only controls

Some current CLI capabilities intentionally do not persist as config:

Structured output requires a one-shot prompt. --output-format stream-json cannot be combined with --json local.

Related references