Territory Grounder · Field guide

Evaluate Territory Grounder in Shadow

Reviewed 2026-11-02. Governed remediation is implemented. Fresh installs start in Shadow: read-only, with no actuation targets. Three repairs demonstrated in an isolated lab; broad production effectiveness is still being evaluated.

The local evaluation bundle builds the control plane, worker and console from the public GitHub repository. PostgreSQL, pgvector and Temporal use public, digest-pinned upstream images. It needs no private registry login.

Tested November 2, 2026 on Linux with Chromium and Firefox: a clean build, database initialization, console login and the read-only runtime posture. Model inference and production actuation are outside this installation check.

This is an empty local environment. It has no estate credentials, effect targets or model provider configured. It lets you inspect the console and configure a deliberate Shadow evaluation. It is not the production deployment recipe.

What you need

• A Linux Docker host, or Docker Desktop with Linux containers, and Docker Compose v2.
• Git, OpenSSL, curl and unzip. Run the preparation script from Bash.
• A practical starting allocation of 4 CPU cores, 8 GB RAM and 20 GB free disk for the build and local stack. This is evaluation guidance, not a measured production minimum. Local model inference needs additional resources.
• Internet access to GitHub, public container registries and Go dependencies for the first build.
• An OpenAI-compatible model gateway and a suitable model before investigating alerts. A local gateway or a remote provider may be used; provider usage has separate costs.

1. Download and inspect

curl -fLO https://territorygrounder.com/downloads/tg-evaluation.zip
unzip tg-evaluation.zip
cd tg-evaluation

Inspect prepare.sh and compose.yaml. The script generates random credentials in a private .env file, checks out the public source revision recorded in source-ref.txt and makes its public database initialization scripts readable by the container. It preserves an existing .env and source checkout.

2. Build and start

bash prepare.sh
docker compose up --build -d
docker compose ps

The first build downloads and compiles the application. Allow several minutes; time depends on the machine and network. The console binds to 127.0.0.1:18480, and the databases are not published on host ports. For another simultaneous evaluation, use a separate folder, a different TG_EVAL_PORT in .env, and docker compose -p another-name for every command.

3. Sign in

Open http://localhost:18480 on the Docker host. Use username operator and the value of TG_OPERATOR_TOKEN from your local .env file. This is a generated secret, not a default password. Do not paste it into an issue or shared log.

Use the exact localhost URL for this local evaluation. Secure session cookies rely on the browser’s localhost exception. A remote or shared deployment requires HTTPS and the full identity/credential setup; do not expose this local port publicly.

4. Verify the starting state

curl -fsS http://localhost:18480/console-healthz
docker compose ps
docker compose logs --tail=30 grounder worker

The health request should return ok; the application, worker, console, Temporal and both databases should stay running. After sign-in, confirm Shadow in the console. Expect an empty estate and no incident history until you configure sources. A healthy container alone is not proof of a completed investigation.

5. Connect a model, then one read-only source

Add these settings to the bundle’s .env, using your own reachable gateway and key:

TG_LITELLM_URL=https://your-model-gateway.example
LITELLM_MASTER_KEY=your-own-gateway-key

The adapter appends /v1/chat/completions, so omit /v1 from this base URL. Check the model adapter, and expose the model aliases required by your chosen configuration. Do not assume an arbitrary provider endpoint is a drop-in gateway. Recreate the application containers after changing environment settings:

docker compose up -d

The bundle deliberately does not supply provider credentials or send a paid test request. Set provider spending limits and the application’s per-session budget before ingesting alerts. Remote providers receive the model inputs you send; a local endpoint has its own hardware requirements. Review the data boundaries.

Then follow the connector setup map and operator documentation to add a single source with read-only credentials. Verify a real investigation in Shadow before considering effect permissions.

Troubleshooting

• The build fails: inspect the failed step in docker compose build --progress=plain. Check disk space and public registry/Go proxy reachability.
• Database initialization fails: inspect docker compose logs postgres. Re-run prepare.sh to restore the public init scripts’ permissions. Keep the generated credentials together with their database volume; changing passwords in .env does not change an existing database role.
• The login page repeats: use localhost, check the generated token and verify grounder is healthy. On a remote host, configure HTTPS first.
• Model requests fail: a gateway is not bundled. Confirm its URL, key, model aliases and reachability from the containers. An unconfigured model does not prevent inspecting the empty console.
• The estate is empty: expected until connectors are configured. The website’s console gallery is explicitly fixture data.

Stop the local stack with docker compose down. This preserves the evaluation’s database volumes. docker compose down -v also deletes this Compose project’s evaluation data; use it only when you intend a fresh start.

Production setup

Use the full deployment documentation for TLS, identity, secret delivery, backups, monitoring, model egress and scoped credentials. Review the image names in the upstream estate-oriented Compose file before using it; the evaluation bundle avoids its private-image defaults by building application images locally.

Actuation requires a separate, deliberate setup. Follow the operator quickstart and validate the safety boundaries. This bundle does not enable actuation.

Support and security

The project is Apache-2.0 and developed in the open. No commercial support SLA is offered by this page. Report reproducible, non-sensitive bugs in GitHub issues, including the source commit, steps and redacted logs.

For a suspected vulnerability, use the private contact options on the maintainer’s website before posting details publicly. Keep credentials, private infrastructure identifiers and incident data out of public reports.

Evaluate in Shadow Read the source