Configuration

Hosted connector clients mostly configure connector URLs and authentication. Self-hosted and development runtimes can also tune server, session, browser, agent, and perception limits with local configuration.

How it works

Self-hosted Scout runtimes look for configuration on startup in the following order:

1. SCOUT_CONFIG environment variable

If set, Scout reads the file at this path. Useful for CI or non-standard project layouts.

2. scout.config.json in the working directory

The default. Place the file next to your package.json and it's picked up automatically.

3. Built-in defaults

If no file is found, every property falls back to a sensible default. Scout works out of the box with zero configuration.

Quick start

For local development, create a scout.config.json in your project root. You only need to include the properties you want to override. Hosted connector clients should normally use the connector setup instructions instead of starting here.

scout.config.jsonJSON

{
  "server": {
    "port": 3000
  },
  "agent": {
    "maxSteps": 50
  }
}

Property reference

Select a section to explore its properties. Every property is optional — omit it to use the default value.

Server

server

Controls the local HTTP server used by self-hosted Scout runtimes. Hosted connector clients normally configure connector URLs in their MCP client instead.

port

numberdefault: 9876

The port the Scout server listens on for HTTP connections. Must be between 1 and 65 535.

Complete example

A complete scout.config.json with every property set to its default value. Copy this as a starting point and remove what you don't need.

Click to expand

Tips

Practical advice for configuring Scout in different environments.

Start minimal

Only override what you need. Every property has a production-ready default. A minimal config is easier to maintain and less likely to conflict with future Scout updates.

Use environment-specific files

Set the SCOUT_CONFIG environment variable to point to different config files for development, staging, and production. This keeps your project root clean and avoids accidental config leaks.

Tune session limits for your workload

If your agents browse complex SPAs with heavy network traffic, increase maxRecentRequests and maxConsoleLogsPerType. For simple page scraping, the defaults are generous.

Agent safety nets

The agent section protects against runaway automation. If your tasks require long multi-step sequences, increase maxSteps. If you run many concurrent agents, raise maxRunners but monitor memory usage.

Perception tuning

Lower the heartbeat intervalMs for faster visual change detection at the cost of CPU. Raise the noiseThreshold if minor CSS animations are triggering false positives.