Running manually

This page is for when you want full control over how WebSummoner starts. If you just want a working setup quickly, the Quick start or Configuration Manager is an easier path. This guide assumes you are comfortable with the command line and basic Docker commands.

1. Prepare the configuration

Create config/browsers.json:

{
  "firefox": {
    "default": "154.0",
    "versions": {
      "154.0": {
        "image": "websummoner/firefox:155.0.0",
        "port": "4444",
        "path": "/"
      }
    }
  }
}

Then pull the browser image so the first session does not wait for a download:

docker pull websummoner/firefox:155.0.0

2. Start WebSummoner

Option 1 — run the binary

Download the binary for your operating system from the releases page and save it as websummoner (or websummoner.exe on Windows). On Linux/macOS add execution permissions with chmod +x websummoner, then run:

./websummoner

A successful start looks like:

2026/08/30 21:23:43 Loading configuration files...
2026/08/30 21:23:43 Loaded configuration from [config/browsers.json]
...
2026/08/30 21:23:43 Listening on :4444

Option 2 — run the container

With Docker installed you can skip the binary and run WebSummoner itself as a container:

docker run -d                                \
  --name websummoner                         \
  -p 4444:4444                               \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $PWD/config/:/etc/websummoner/:ro       \
  websummoner/websummoner:latest-release

The Docker socket mount lets WebSummoner launch browser containers on the same host.

Useful Docker references for the flags above:

Bind mounts — how -v /host/path:/container/path:ro works, path formats per OS
docker run reference — every flag used here
Docker networks — bridge vs custom networks (-container-network)

Ready-made browser images

Prebuilt images are maintained for several browsers:

The complete list with versions and drivers is in Browser images. Build files live in the images repository — issues and requests for new versions are welcome.

All images support UTF-8 locales, which matters if your tests save files with non-ASCII names. Enable a specific locale through environment variables in browsers.json:

{
  "chrome": {
    "default": "152.0",
    "versions": {
      "152.0": {
        "image": "websummoner/chrome:152.0",
        "env": ["LANG=ru_RU.UTF-8", "LANGUAGE=ru:en", "LC_ALL=ru_RU.UTF-8"]
      }
    }
  }
}

Running on Windows

Everything works, but Docker volume mounts are the tricky part:

Replace backslashes (\) with forward slashes (/) and lowercase the drive letter — C:\Users\admin becomes /c/Users/admin.
Mount the Docker socket with two leading slashes: -v //var/run/docker.sock:/var/run/docker.sock

A typical startup (configuration at C:\Users\admin\websummoner):

docker run -d --name websummoner `
  -p 4444:4444 `
  -v //var/run/docker.sock:/var/run/docker.sock `
  -v /c/Users/admin/websummoner:/etc/websummoner:ro `
  websummoner/websummoner:latest-release