Add a Remote Environment

Share captured traces across your team by deploying a remote Loop Server.

---

Understanding Environments

An environment is where your projects and traces live. Lens Loop supports two types:

Environment	Description	Best For
Local	Built into Lens Loop, runs on your machine	Individual development
Remote	Shared Loop Server accessible by your team	Team collaboration

By default, you have a local environment. Adding a remote environment lets multiple developers see the same traces.

---

Deploy a Remote Loop Server

Run Loop Server using Docker to create a shared environment.

Docker Compose Setup

Create a docker-compose.yml file:

docker-compose.yml

services:
  server:
    image: ghcr.io/lensapp/lens-loop-server:beta
    container_name: lens-loop-server
    ports:
      - "31301:31300" # (1)!
    environment:
      - SERVER_NAME=Team Environment # (2)!
      - NODE_ENV=production
      - HOST=0.0.0.0
      - PORT=31300
      - LENS_SERVER_ACCESS_POLICY=${LENS_SERVER_ACCESS_POLICY} # (3)!
      - OTEL_API_KEY=${OTEL_API_KEY} # (4)!
      - DATABASE_PATH=/app/data/server.db
    volumes:
      - server-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/nodejs/bin/node", "-e", "require('http').get('http://127.0.0.1:31300/api/v1/healthz', (r) => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
      interval: 30s
      timeout: 3s
      start_period: 10s
      retries: 3

volumes:
  server-data:
    name: lens-loop-server-data

1. Exposes the server on port 31301 (use any available port)
2. Display name shown in Lens Loop's Navigator
3. Comma-separated Lens ID usernames allowed to connect
4. Secret key for authentication — change this!

Configuration Reference

Variable	Description	Required
SERVER_NAME	Friendly name displayed in Lens Loop	Yes
OTEL_API_KEY	Secret key for authenticating connections	Yes
LENS_SERVER_ACCESS_POLICY	Comma-separated list of allowed Lens ID usernames	Yes
DATABASE_PATH	Path where traces are stored	Yes
HOST	Bind address (use 0.0.0.0 for external access)	Yes
PORT	Internal port (typically 31300)	Yes

Start the Server

# Create a .env file with your configuration
echo 'LENS_SERVER_ACCESS_POLICY=user1,user2,user3' >> .env
echo 'OTEL_API_KEY=your-secret-key-here' >> .env

# Start the server
docker compose up -d

Production Deployments

For production, place a reverse proxy (Traefik, Caddy, or Nginx) in front of Loop Server to handle TLS. Never expose the server over plain HTTP on the internet.

---

Connect to a Remote Environment

Once your server is running, add it to Lens Loop:

1. In the Navigator, click Environments
2. Click Add Remote Environment
3. Enter your server address (e.g., http://your-server:31301)
4. Click Add after Lens Loop confirms the connection

---

Capturing to Remote Environments

When capturing traffic to a remote environment, point your application's base URL to the remote server instead of localhost:

client = OpenAI(
    base_url="http://your-server:31301/openai/v1",  # Remote server
    api_key=os.environ.get("OPENAI_API_KEY"),
    default_headers={
        "X-Loop-Project": "my-project",
    }
)

---

Next Steps

• Start Capturing

  ---

  Route your application's traffic through the remote server.

  Capture Traffic

• Explore the Interface

  ---

  Learn about Navigator, Traces, and the Details panel.

  Using Lens Loop