Self-Host Versus Incident in Training Mode with Localtonet

What this deployment runs

Versus Incident accepts incidents through two complementary paths. Its AI SRE agent reads configured log sources, learns recurring patterns, and can identify lines it has not seen before. Its webhook receiver accepts incidents forwarded by monitoring systems and custom scripts. Both paths feed the same downstream notification, templating, and on-call workflow, so enabling the agent does not prevent you from forwarding conventional alerts later.

This tutorial focuses on the AI-agent path because training mode provides a deliberately cautious starting point. In training mode, the agent watches its configured sources and builds knowledge of normal patterns, but it does not send alerts. That separation lets you validate source access, persistence, and dashboard behavior before progressing toward any mode capable of creating incidents.

Training, shadow, and detect modes

The mode progression is important because the three modes have materially different outcomes. Start with training, observe what the agent learns, then use shadow mode to evaluate what it would classify as unusual. Detect mode should come only after you trust the source configuration and the resulting decisions.

Prerequisites and deployment decisions

Prepare a host that can run Docker containers and retain local configuration and data directories. The official startup example uses shell syntax such as $(pwd), so the commands below are directly suited to a POSIX-style shell. If you use PowerShell, Command Prompt, or another shell, translate only the host-path expression according to that shell's rules. The container paths must remain /app/config and /app/data.

You need the following before installation:

• A working Docker installation with permission to start containers and publish host ports.
• Host port 3000 available for Versus Incident.
• Host port 6379 available if you use the documented Redis command exactly as shown.
• A writable configuration directory and a writable data directory.
• A config.yaml file and an agent_sources.yaml file that match the Versus Incident version you run.
• At least one log source that the Versus Incident container can actually reach and read.
• A strong gateway secret that is not committed to source control, pasted into logs, or shared in screenshots.
• For the optional remote-access stage, the Localtonet client installed on the host or another device that can reach the published port.

Choose log sources before starting the agent

The agent cannot train without input. Its agent_sources.yaml file tells it where the logs are and how to consume them. The exact source schema is source-specific and was not included in the evidence supplied for this article. It would be unsafe to guess field names, authentication properties, file paths, or source defaults. Use the version-matched AI Agent Getting Started configuration from the Versus Incident project and replace its example source with a log location that is valid in your environment.

Pay particular attention to the difference between a host path and a container path. A log file available as /var/log/example.log on the Docker host is not automatically visible at that path inside the container. If your selected source reads local files, its required files must be mounted into the container and the source configuration must reference the in-container path. The supplied startup command mounts only the configuration and application data directories. Add no speculative log mount from this guide; derive the necessary read-only mount from your chosen source and the current project instructions.

Understand the two kinds of persistence

Redis and the application data mount have separate purposes in the documented setup. Redis remembers where the agent left off in each source. The Versus configuration example identifies file storage as the currently implemented backend for the pattern catalog, shadow log, and incident history. The local data directory mounted at /app/data therefore deserves persistent storage and normal backup treatment.

The configuration lists file, redis, and database as possible storage type names, but it explicitly describes Redis and database storage as configuration stubs. Do not select those names for the pattern catalog on the assumption that they are complete storage implementations. Redis in this workflow is for source cursor persistence, not a replacement for the file-backed application store.

Prepare the Versus Incident configuration

Create dedicated directories in the working directory from which you will run Docker:

mkdir -p config data

Place config.yaml and agent_sources.yaml in the local config directory. The bind mount used later maps that directory to /app/config in the container. The source path in the documented configuration is relative to the main configuration file, which allows the two files to remain together.

The following fragment contains only settings established by the documented configuration example. It is useful for understanding the relationship between the service, gateway secret, file storage, and agent. It is not a substitute for a complete version-matched configuration, especially because the exact source definitions and any desired notification integrations are specific to your deployment.

name: versus
host: 0.0.0.0
port: 3000

gateway_secret: ${GATEWAY_SECRET}

storage:
  type: file
  file:
    max_incidents: 1000

agent:
  enable: true
  mode: training
  poll_interval: 30s
  sources_path: ./agent_sources.yaml
  catalog:
    persist_interval: 30s
    auto_promote_after: 100
  redaction:
    enable: true
    redact_ips: false

Binding the service to 0.0.0.0 inside its container allows Docker's published port to reach it. The host mapping later publishes container port 3000 as host port 3000. The gateway_secret value is read from the GATEWAY_SECRET environment variable rather than being written directly into this YAML fragment.

All administrative endpoints under /api/admin/* and /api/agent/* require the shared gateway secret. API clients send it through the X-Gateway-Secret header. The dashboard exchanges the secret for an opaque HttpOnly session cookie. Keep the secret out of browser URLs because URLs can be retained in history, proxy logs, and analytics systems.

Build a version-matched source file

Your agent_sources.yaml must come from the current Versus Incident source instructions for the log integration you intend to use. Confirm all of the following before starting:

• The source type and every property name are supported by your selected release.
• The container can resolve the source hostname or access the configured in-container file path.
• Any required credentials are supplied through an appropriate secret mechanism rather than committed in YAML.
• The source initially points to a controlled log stream whose contents you understand.
• File permissions, network policies, and upstream allowlists permit read access from the container.

This is the one project-specific portion that cannot be made safely copy-and-paste from the supplied evidence. Different log sources require different fields, and inventing a generic schema could lead to a container that starts but never trains. Resolve this file before treating the installation as complete.

Install and start Versus Incident with Docker

Run Redis first, then start Versus Incident. This preserves the documented sequence and makes the cursor service available before the agent attempts to connect.

Start Redis

docker run -d --name versus-redis -p 6379:6379 redis:7

Confirm that Docker created the container:

docker ps --filter name=versus-redis

If it is absent from the running-container list, inspect both running and stopped containers and then read its logs:

docker ps -a --filter name=versus-redis
docker logs versus-redis

Start the Versus Incident container

Run the following from the directory containing config and data. Replace change-me with your own strong secret before execution.

docker run -p 3000:3000 \
  -e GATEWAY_SECRET=change-me \
  -e AGENT_ENABLE=true \
  -e AGENT_MODE=training \
  -e REDIS_HOST=host.docker.internal \
  -e REDIS_PORT=6379 \
  -v "$(pwd)/config:/app/config" \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/versuscontrol/versus-incident

The documented command runs the Versus container in the foreground. That is helpful for the first launch because configuration and connection errors appear directly in the terminal. Stop the foreground process with the normal interrupt for your shell when you need to revise the configuration.

Publishing Redis on 0.0.0.0:6379 may make it reachable from networks attached to the host, depending on the host firewall and Docker configuration. Do not treat the example as a production network-security design. Restrict Redis to the smallest necessary scope, and never expose it through a Localtonet tunnel for this workflow.

Verify the dashboard, agent, persistence, and webhook route

Verification should move from the inside out. First prove that the container remains running. Then prove that the host can reach port 3000. After that, inspect the dashboard and source activity. Add Localtonet only when all local checks pass.

Check the container state and logs

If you later run the service in the background using a deployment method supported by your environment, list its container and inspect its logs with the relevant container name or ID:

docker ps
docker logs versus-incident

The documented startup command does not assign the Versus container a fixed name, so versus-incident in the second command is only valid if you explicitly use that name in your own container management. Otherwise, copy the generated name or container ID from docker ps. This distinction prevents a misleading “No such container” error during troubleshooting.

Test the local HTTP service

Open the dashboard in a browser:

http://localhost:3000/

You can also make a basic HTTP request from the host:

curl http://localhost:3000/

An HTTP response confirms that Docker's port publication reaches the embedded web service. It does not prove that Redis is connected or that the agent can read its sources, so continue with dashboard and log inspection.

Confirm the training state

In the dashboard, verify that the agent is enabled and that its mode is training. Review the learned patterns as source data arrives. The agent's documented default polling example is 30 seconds, so source observations are not necessarily instantaneous. The catalog persistence example also uses a 30-second interval. Avoid interpreting a short delay as a failed deployment without first checking the process logs and waiting for the configured intervals.

Training mode should not generate real incident notifications. If notifications appear, verify the effective mode rather than assuming the YAML file won. The Docker command explicitly supplies AGENT_MODE=training, and environment-variable settings may override file values. Also distinguish AI-generated incidents from webhook incidents sent independently to /api/incidents.

Validate cursor persistence carefully

Redis is intended to remember where the agent stopped in each log source. A practical verification is to allow the agent to consume a controlled stream, stop and start the application using your normal Docker process, and inspect whether it resumes rather than treating the entire source as new. Do this only with disposable or well-understood test data. The exact dashboard labels and log messages can change by release, so this guide does not prescribe text that may not exist in your version.

Recognize the webhook endpoint without guessing its payload

The service exposes POST /api/incidents for monitoring tools. A browser navigation sends a GET request, so opening that path in a browser is not a valid webhook test. An arbitrary empty POST is also not a useful test because the endpoint expects a supported request shape. Configure a known sender or follow the project's version-matched webhook example when you are ready to test that path.

Access Versus Incident remotely with a Localtonet HTTP tunnel

Once the dashboard works locally, Localtonet can expose the HTTP service without an inbound router rule or public IP address. Our client establishes an outbound connection to a Localtonet relay server. The resulting HTTP tunnel supplies a public HTTPS address that forwards requests to the selected local IP address and port.

Creating a tunnel does not start it automatically. The selected Localtonet device must remain connected, and the tunnel itself must be running. If either stops, the public address will no longer reach Versus Incident.

HTTP Process Type controls how the public address is assigned. Random Sub Domain, Custom Sub Domain, and Custom Domain all serve the same local content through a public HTTPS address. Option and plan availability can vary. If you choose a custom domain, check the current DNS instructions before creating records because exact requirements are not established in the supplied context.

For the current dashboard sequence and field names, consult our Localtonet HTTP tunnel documentation.

Set public_host when proxy behavior requires it

Versus Incident documents deployments behind TLS-terminating or Host-rewriting proxies. In those arrangements, configure public_host to the exact origin visible in the browser. An origin includes the scheme and hostname, plus a port only when the browser-visible URL uses a non-default port.

For example, if Localtonet assigns https://example-subdomain as the public origin, the Versus setting must match that exact browser-visible origin rather than the internal target http://127.0.0.1:3000. Use the real assigned value from your tunnel. Do not copy a placeholder hostname from a tutorial.

Because the supplied evidence does not establish an environment-variable name for public_host, set the YAML property using the syntax documented for your Versus Incident release. It is also not established whether your release reloads this property dynamically. Apply configuration changes through the project's documented reload or restart procedure rather than assuming they take effect immediately.

Remote webhook delivery

The same HTTP tunnel can route valid POST requests to the webhook endpoint. If the assigned origin is represented here as https://PUBLIC-ORIGIN, a sender would target the corresponding https://PUBLIC-ORIGIN/api/incidents route. Replace the placeholder with the exact assigned origin and configure the sender according to Versus Incident's supported webhook format.

Do not confuse a reachable route with an authenticated and validated integration. Test request signatures, shared credentials, templates, retry behavior, and payload compatibility according to the sending system and the current Versus documentation. Never publish the administrative gateway secret as part of a webhook URL.

Security and exposure checklist

Self-hosting keeps deployment control in your environment, but it also makes you responsible for the container host, application credentials, log data, upgrades, backups, and public exposure decisions. Treat the dashboard as an administrative interface rather than an ordinary public website.

Keep Redis private

The Redis instance stores source cursor state for this workflow. It is not the dashboard and should not receive a public tunnel. Restrict host port 6379 according to your Docker and host-network design. If your environment cannot safely publish Redis on the host, use a supported private container network configuration rather than accepting broad exposure for convenience.

Separate administration from incident ingestion

Administrative APIs and webhook ingestion have different purposes. The gateway secret protects documented administrative and agent API paths, while webhook authentication and payload requirements depend on the integration. Do not assume that securing one route automatically secures every other route. Inventory which paths must be remotely reachable and avoid exposing functionality that has no remote use case.

Plan mode changes as production changes

Moving from training to shadow is a validation step. Moving from shadow to detect enables real incident creation. Treat both changes as controlled configuration changes with review and rollback plans. Confirm notification channels and on-call integrations before detect mode so test or misclassified events do not create unnecessary escalation.

Common operations and troubleshooting

Stop and remove the containers

Use the actual Versus container name or ID shown by docker ps. The Redis container has the documented fixed name:

docker stop VERSUS_CONTAINER
docker stop versus-redis

Removing containers does not automatically remove the host directories mounted as config and data. Verify their contents and backup status before deleting them manually. If you remove Redis without preserving its data through a separately configured persistence strategy, cursor continuity may be lost. The basic Redis command supplied here does not document a Redis persistence volume, so do not claim restart durability beyond what you have tested.

The dashboard does not open on localhost

• Confirm that the Versus container is still running.
• Inspect startup output for malformed YAML, missing files, and permission errors.
• Check whether another process already owns host port 3000.
• Confirm the mapping is 3000:3000 and the service is configured to listen on 0.0.0.0 inside the container.
• Verify that the bind mounts resolve to the intended absolute host directories.
• Test curl http://localhost:3000/ on the Docker host before testing from another device.

The service runs, but the agent does not learn

• Confirm that the effective agent mode is training and that the agent is enabled.
• Check whether agent_sources.yaml is at the path resolved from sources_path.
• Validate the source file against documentation for the exact project version.
• For file sources, confirm that the file exists inside the container, not merely on the host.
• For network sources, confirm DNS resolution, routing, credentials, and upstream allowlists from the container environment.
• Allow for the configured polling and catalog persistence intervals before concluding that nothing is happening.

Versus cannot connect to Redis

• Check that versus-redis is running and listening on the published port.
• Inspect the Redis logs for startup failures.
• Determine whether host.docker.internal resolves from the Versus container on your Docker platform.
• Confirm that local firewall policy permits the required container-to-host connection.
• If you adopt private Docker networking, use the hostname and network configuration supported by that design instead of mixing it with the host-published-port example.

The Localtonet URL returns an error

• Verify that the Localtonet client shows as connected.
• Confirm that the tunnel was started after creation.
• From the Localtonet client device, request the exact local target configured for the tunnel.
• If the client is on the Docker host, verify http://127.0.0.1:3000/.
• If the client is on another device, do not use that device's loopback address. Use the Docker host address reachable from the client.
• Check whether the selected relay server remains available in the current dashboard.
• Inspect Versus logs to determine whether the request reaches the application.

The dashboard loads but redirects or links incorrectly

Compare the browser's visible origin with the Versus public_host value. The scheme, hostname, and any explicit non-default port must match. Do not configure the internal Docker target as the public origin. Apply the corrected value through the configuration process supported by your installed release.

The tunnel works, but webhook delivery fails

First distinguish transport failure from application rejection. A tunnel problem generally means the sender cannot establish an HTTP exchange with the public address. An application problem means Versus responds but rejects the method, payload, authentication, or content. Confirm that the sender uses POST, targets /api/incidents, and sends a payload supported by the configured integration. Review both sender delivery logs and Versus application logs.

Upgrade planning

The documented image reference does not include a tag. Pulling an untagged image can change the software version available to a future deployment. For repeatable production operations, review the project's current release guidance and use a verified image tag only when the registry documents that tag. Back up configuration and persistent data, read release notes, and test upgrades in a non-production environment before replacing a working container.

This article does not present a Helm installation. Although the project repository contains Helm-related material, the supplied evidence does not establish a complete official Helm procedure, required values, or supported upgrade path. Docker is therefore the only installation workflow documented here.

Frequently asked questions