Skip to content

Add a remote environment#

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

Overview#

Within an environment, you can create projects. Each project contains traces from the corresponding LLM application.

Environment Description Use case
Local Runs inside Lens Loop on your machine Individual development
Remote A shared Loop Server accessible by your team Team collaboration

By default, Lens Loop uses a local environment. Use a remote environment to allow multiple developers to view and work with the same traces.

Deploy a remote server#

Use Docker to run the Loop Server and create a remote environment.

Docker Compose Setup#

Create a file named docker-compose.yml with the following content:

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. The mapping 31301:31300 exposes the server on host port 31301. You can choose any available host port.
  2. SERVER_NAME is the display name shown in the Lens Loop Navigator.
  3. LENS_SERVER_ACCESS_POLICY is a comma-separated list of Lens ID usernames allowed to connect.
  4. OTEL_API_KEY is a secret used to authenticate connections. Use a strong, unique key.

Configuration Reference#

Variable Description Required
SERVER_NAME 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 IDs Yes
DATABASE_PATH Path where traces are stored inside the container Yes
HOST Bind address (use 0.0.0.0 for external access) Yes
PORT Internal port (default 31300) Yes

Start the server#

Create a .env file with the required variables, then start the service.

# 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

Warning for production deployments

  • Use a reverse proxy (for example, Traefik, Caddy, or Nginx) to terminate TLS.
  • Do not expose the Loop Server over plain HTTP on the internet.
  • Protect your OTEL_API_KEY and restrict LENS_SERVER_ACCESS_POLICY.

Connect to a remote environment#

After the server starts, add it to Lens Loop:

  1. Open the Navigator and click Environments.
  2. Click Add Remote Environment.
  3. Enter the server address, for example http://your-server:31301.
  4. Click Add after Lens Loop confirms the connection.

Capture to a remote environment#

Point your application to the remote server instead of localhost.

See the example for Python below:

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",
    }
)

See also