How to Deploy the Open-Code-Review Session Viewer for Team Code Review Browsing

Deploy the session viewer for team code review browsing by running the ocr viewer command on a shared host, binding to a reachable IP address, and configuring OCR_VIEWER_ALLOWED_HOSTS to whitelist your team's access points.

The Open-Code-Review Session Viewer is a lightweight embedded HTTP server that renders JSONL session logs into an interactive browser-based UI for post-review analysis. While designed for local use, deploying it for team-wide access requires only binding to a network-accessible address and adjusting its DNS-rebinding protection settings.

What the Session Viewer Does

The viewer scans the ~/.opencodereview/sessions/ directory lazily on each request, presenting three main views:

• Repository list (/) — all repositories with stored sessions
• Session list (/r/<repo>) — newest sessions for a specific repository
• Session detail (/r/<repo>/<sessionID>) — full interactive review view

The core HTTP server implementation lives in internal/viewer/server.go, where the mux is created and the listener started【internal/viewer/server.go:17‑62】. Sessions appear instantly without restarts because the viewer reads the filesystem on every request【pages/src/content/docs/en/viewer.md:20‑23】.

Basic Deployment for Team Access

Step 1: Install and Verify OCR

# One-line installer from the Alibaba repository

curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh

# Verify the viewer subcommand exists

ocr viewer --help

Step 2: Start on a Reachable Host Address

By default, ocr viewer binds to localhost. For team access, specify your host's LAN IP or 0.0.0.0:

# Bind to a specific internal IP

ocr viewer --addr 192.168.10.5:5483

The server prints its startup URL to stdout. However, accessing this from another machine will fail until you configure the host allowlist.

Step 3: Configure OCR_VIEWER_ALLOWED_HOSTS

The viewer implements DNS-rebinding protection through a host whitelist. The hostGuard middleware in internal/viewer/hostguard.go rejects any request whose Host header isn't explicitly allowed【internal/viewer/hostguard.go:81‑100】.

Set the OCR_VIEWER_ALLOWED_HOSTS environment variable before starting:

export OCR_VIEWER_ALLOWED_HOSTS=192.168.10.5,team-reviews.local,ocr.internal
ocr viewer --addr 192.168.10.5:5483

The allowlist is parsed by resolveAllowedHostsFromEnv and built into a lookup map by buildAllowedHosts【internal/viewer/hostguard.go:10‑36】. Include every hostname or IP your team will use to access the viewer.

Reverse Proxy Deployment (Recommended for Production)

For HTTPS termination, authentication, or integration with existing infrastructure, run the viewer behind a reverse proxy.

Viewer Configuration

# Bind to localhost only; the proxy handles external access

export OCR_VIEWER_ALLOWED_HOSTS=localhost,ocr-viewer.company.internal
ocr viewer --addr 127.0.0.1:5483

NGINX Example

server {
    listen 443 ssl;
    server_name ocr-viewer.company.internal;

    ssl_certificate /etc/ssl/certs/ocr-viewer.crt;
    ssl_certificate_key /etc/ssl/private/ocr-viewer.key;

    location / {
        proxy_pass http://127.0.0.1:5483/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The critical line is proxy_set_header Host $host — this preserves the original hostname so it matches your OCR_VIEWER_ALLOWED_HOSTS entry.

Traefik Example

# docker-compose.yml snippet

services:
  ocr-viewer:
    image: ocr-viewer:latest
    environment:
      - OCR_VIEWER_ALLOWED_HOSTS=ocr-viewer.company.internal
    command: ["ocr", "viewer", "--addr", "0.0.0.0:5483"]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ocr.rule=Host(`ocr-viewer.company.internal`)"
      - "traefik.http.services.ocr.loadbalancer.server.port=5483"

Container Deployment

No official Docker image exists, but you can package the binary yourself:

FROM alpine:3.19
RUN apk add --no-cache ca-certificates
COPY ocr /usr/local/bin/ocr
ENV OCR_VIEWER_ALLOWED_HOSTS=0.0.0.0
EXPOSE 5483
ENTRYPOINT ["ocr", "viewer", "--addr", "0.0.0.0:5483"]

Build and run:

docker build -t ocr-viewer .
docker run -d \
  -p 5483:5483 \
  -v ~/.opencodereview/sessions:/root/.opencodereview/sessions:ro \
  ocr-viewer

Mount your sessions directory read-only to share existing review data.

Security Considerations

• No data leaves the host — The viewer only reads local JSONL files; nothing is uploaded to external services【pages/src/content/docs/en/viewer.md:51‑55】.
• Delete sensitive sessions — Remove ~/.opencodereview/sessions/ contents when reviews conclude, or use a temporary HOME directory for sensitive codebases【pages/src/content/docs/en/viewer.md:56‑63】.
• Restrict network access — Bind to internal interfaces only; use firewall rules or VPNs rather than exposing directly to the internet.

Summary

• The session viewer is a local HTTP server that renders OCR session logs; team deployment requires network binding and host whitelisting.
• Set OCR_VIEWER_ALLOWED_HOSTS to every IP or hostname your team will use — this is mandatory for non-loopback access.
• For production use, run behind a reverse proxy with HTTPS and preserve the Host header.
• Containerization requires custom packaging; mount session directories read-only.

Frequently Asked Questions

How do I allow multiple hostnames for the session viewer?

Set OCR_VIEWER_ALLOWED_HOSTS as a comma-separated list: export OCR_VIEWER_ALLOWED_HOSTS=host1,host2,10.0.0.5. The viewer parses this in resolveAllowedHostsFromEnv and checks every incoming request against the resulting set【internal/viewer/hostguard.go:10‑36】.

Why do I get "host not allowed" errors after changing the bind address?

The viewer's DNS-rebinding protection requires explicit hostname whitelisting. Binding to 0.0.0.0 or a LAN IP without updating OCR_VIEWER_ALLOWED_HOSTS triggers the hostGuard middleware to reject requests【internal/viewer/hostguard.go:81‑100】. Always match your --addr binding with corresponding entries in the allowlist.

Can I run the viewer without installing OCR on every machine?

Yes — deploy the viewer on a single shared host and have team members access it via browser. The ocr binary only needs installation on the server. Alternatively, use the Docker approach above to containerize the deployment.

Where are session files stored and how do I clean them up?

Sessions write to ~/.opencodereview/sessions/ as JSONL files. The viewer scans this directory lazily, so deletions take effect immediately. For sensitive code, either delete files manually after review or set a temporary HOME environment variable so sessions discard on shell exit【pages/src/content/docs/en/viewer.md:56‑63】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}