Codakey
Play
← Back to yepanywhere

How to Deploy & Use yepanywhere

This guide will walk you through deploying and using Yep Anywhere, a self-hosted web UI for Claude and Codex.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: Version 18 or higher.
  • npm or pnpm: A package manager for Node.js. pnpm is recommended for development.
  • Git: For cloning the repository.
  • Claude Code CLI or Codex CLI: Yep Anywhere integrates with your existing CLI sessions. Install at least one of these agents.
    • For Claude Code: Install the official @anthropic-ai/claude-agent-sdk.
  • OpenSSL: Required for generating self-signed certificates for HTTPS (if self-hosting HTTPS).

Installation

You can install Yep Anywhere either globally via npm or by cloning the source repository.

Global Installation (Recommended for Users)

This method is the quickest way to get started.

npm i -g yepanywhere

Installation from Source (Recommended for Developers)

If you plan to contribute or need the latest development features, install from source.

  1. Clone the repository: 
    git clone https://github.com/kzahel/yepanywhere.git
cd yepanywhere
  2. Install dependencies: 
    pnpm install
  3. Build the project: 
    pnpm build

Configuration

Yep Anywhere is largely configuration-free, leveraging your existing CLI sessions. However, you can configure remote access and other settings.

Remote Access Configuration

For headless setups or to pre-configure remote access, use the CLI:

yepanywhere --setup-remote-access --username myserver --password "secretpass123"

This command sets up your server to connect to the public relay with the specified credentials.

Environment Variables

While not explicitly detailed for runtime, the project uses environment variables for various settings, especially during development. For example, getRelayDebugEnabled suggests a debug flag. Consult DEVELOPMENT.md for specific development-related environment variables.

HTTPS Configuration

If you choose to self-host HTTPS, Yep Anywhere can generate a self-signed certificate:

// packages/server/src/https/self-signed.ts
ensureSelfSignedCertificate();

This function ensures a self-signed certificate exists, which is used if HTTPS is enabled without a custom certificate.

Build & Run

Running Locally (Development)

After installing from source, you can start the development server.

pnpm start

This will typically start the server on http://localhost:3400. The application will automatically detect installed CLI agents.

Running Locally (Production/Global Install)

If you installed globally:

yepanywhere

If you built from source:

pnpm start

Open your browser to http://localhost:3400.

Deployment

Yep Anywhere is designed for self-hosting. Here are common deployment strategies:

1. Local Machine (Default)

The simplest deployment is running Yep Anywhere directly on your development machine. This allows you to supervise agents running on the same machine.

  • Command: yepanywhere or pnpm start
  • Access: http://localhost:3400

2. Remote Access via Public Relay (Easiest Remote)

Yep Anywhere provides a free public relay for end-to-end encrypted remote access.

  1. Start Yep Anywhere on your host machine.
  2. Configure Remote Access: 
    yepanywhere --setup-remote-access --username your_unique_username --password "your_strong_password"
    Alternatively, configure it through the UI settings.
  3. Connect: Navigate to https://yepanywhere.com/remote in your browser and enter your configured username and password.

3. Self-Hosted Remote Access (Advanced)

For full control, you can use a reverse proxy or VPN solution.

  • Tailscale: A popular option for creating secure private networks. Install Tailscale on your host machine and your client devices, then access Yep Anywhere via its Tailscale IP address.

  • Caddy: A modern web server that can automatically manage SSL certificates.

    your.domain.com {
    reverse_proxy localhost:3400
}

    Replace your.domain.com with your actual domain and ensure Caddy is configured to proxy requests to Yep Anywhere's local port (default 3400).

  • Other Reverse Proxies: Nginx, Apache, or similar can also be used with SSL termination. Ensure they proxy WebSocket connections correctly.

    Example Nginx configuration snippet:

    server {
    listen 80;
    listen 443 ssl;
    server_name your.domain.com;

    # SSL configuration here (cert, key)

    location / {
        proxy_pass http://localhost:3400;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Deployment Platforms

Given its Node.js backend and local file system interaction, Yep Anywhere is best suited for:

  • Virtual Private Servers (VPS): DigitalOcean, Linode, AWS EC2, Google Cloud Compute Engine.
  • Dedicated Servers: For maximum performance and control.
  • Local Machines: Running directly on your workstation or a Raspberry Pi.

It is less suited for serverless or container-orchestration platforms without specific persistent storage and network configurations due to its reliance on local CLI sessions and file system persistence.

Troubleshooting

"Cannot find Claude Code CLI" or "Cannot find Codex CLI"

  • Verify Installation: Ensure claude (from @anthropic-ai/claude-agent-sdk) or codex CLIs are correctly installed and available in your system's PATH.
  • Check CLI Functionality: Open a new terminal and try running claude help or codex help to confirm they work independently.
  • Restart Yep Anywhere: Sometimes a restart is needed after installing new CLIs.

Remote Access Connection Issues

  • Firewall: Ensure port 3400 (or your custom port) is open on your host machine if you're trying to connect directly without a relay or VPN.
  • Credentials: Double-check the username and password used for the public relay. They are case-sensitive.
  • Internet Connectivity: Verify both the server and client have stable internet connections.
  • Server Logs: Check the server's console output for any errors related to WebSocket connections or authentication. Look for messages from SecureConnection.ts or ws-relay-handlers.ts.

UI Not Loading / Blank Screen

  • Browser Console: Open your browser's developer tools (F12) and check the Console tab for JavaScript errors.
  • Server Logs: Check the terminal where Yep Anywhere is running for any backend errors.
  • Port Conflict: Ensure no other application is using port 3400. You might see an error like "Address already in use".

Sessions Not Appearing

  • CLI Activity: Ensure you have active or recent sessions with your Claude Code or Codex CLI. Yep Anywhere piggybacks on their history.
  • File Permissions: Verify that Yep Anywhere has read access to the directories where your CLI agents store their session history.
    • The SessionIndexService (from packages/server/src/indexes/index.ts) and ProjectScanner (packages/server/src/projects/scanner.ts) are responsible for detecting sessions.

Push Notifications Not Working

  • Browser Permissions: Ensure you have granted notification permissions to yepanywhere.com (for relay) or your self-hosted domain.
  • VAPID Keys: Verify that VAPID keys are generated and configured correctly. PushService (packages/server/src/push/index.ts) handles this.
  • Network Connectivity: Push notifications rely on external services (e.g., Web Push Protocol). Ensure your server can reach these services.

Slow Performance

  • Server Resources: Check CPU and memory usage on the machine running Yep Anywhere, especially if you have many active sessions.
  • Network Latency: High latency between your client and the server (or relay) can impact responsiveness.
  • Browser Performance: Ensure your browser is up-to-date and not overloaded with other tabs or extensions.
← Project overviewView alternatives to yepanywhere →