### Build and Run Yep-Anywhere

Source: https://github.com/kzahel/yepanywhere/blob/main/docker/README.md

Initial setup commands to build the image, install dependencies, and start the container.

```bash
# Build the image
docker compose -f docker/docker-compose.yml build

# First time: install dependencies
docker compose -f docker/docker-compose.yml run --rm yep-sandbox pnpm install

# Run (sandboxed, full network)
docker compose -f docker/docker-compose.yml up
```

--------------------------------

### Install and run via npm

Source: https://github.com/kzahel/yepanywhere/blob/main/README.md

Use these commands to install the package globally and start the application.

```bash
npm i -g yepanywhere
yepanywhere
```

--------------------------------

### Initialize Core Development Environment

Source: https://github.com/kzahel/yepanywhere/blob/main/DEVELOPMENT.md

Alternative setup command to install only the core workspace, excluding the relay workspace.

```bash
pnpm setup:core
pnpm dev
```

--------------------------------

### Install and configure cloudflared on Linux

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/relay/README.md

Downloads the cloudflared binary, sets permissions, and installs it as a system service using a provided token.

```bash
curl -fsSL \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
  -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared
# One-time service-install command (with token) from the dashboard:
sudo cloudflared service install <TOKEN>
```

--------------------------------

### Define InstallState and InstallService

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/project/relay-implementation-plan.md

Defines the structure for installation state and the service class responsible for managing the local install ID.

```typescript
interface InstallState {
  version: number;
  installId: string;    // crypto.randomUUID()
  createdAt: string;
}

class InstallService {
  private state: InstallState;
  private filePath: string;

  constructor(dataDir: string) {
    this.filePath = path.join(dataDir, "install.json");
    this.state = this.load();
  }

  private load(): InstallState {
    // If file exists and valid, return it
    // Otherwise generate new installId, persist, return
  }

  getInstallId(): string {
    return this.state.installId;
  }
}
```

--------------------------------

### Control Command JSON Examples

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/android-device-server/README.md

Example JSON payloads for sending control commands to the device server.

```json
{"cmd":"touch","touches":[{"x":0.5,"y":0.3,"pressure":1.0}]}
```

```json
{"cmd":"key","key":"back"}
```

```json
{"cmd":"capture_settings","maxWidth":360}
```

--------------------------------

### Start Development Environment

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tasks/2026-01-12-acp-integration.md

Launch the yepanywhere development server for manual testing.

```bash
pnpm dev
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/kzahel/yepanywhere/blob/main/DEVELOPMENT.md

Standard commands to clone the repository and start the development server.

```bash
git clone https://github.com/kzahel/yepanywhere.git
cd yepanywhere
pnpm install
pnpm dev
```

--------------------------------

### POST /emulators/:id/start

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/project/android-emulator-remote-control.md

Starts a specific Android emulator.

```APIDOC
## POST /emulators/:id/start

### Description
Starts the emulator with the specified ID.

### Method
POST

### Endpoint
/emulators/:id/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The emulator identifier
```

--------------------------------

### Install ACP SDK

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tasks/2026-01-12-acp-integration.md

Install the required Agent Client Protocol SDK package using pnpm.

```bash
pnpm add @agentclientprotocol/sdk
```

--------------------------------

### List Available Ollama Models

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/codex-oss.md

Verify installed models and their configurations.

```bash
ollama list
```

--------------------------------

### Initialize Relay Database

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/project/relay-implementation-plan.md

Database setup using better-sqlite3.

```typescript
import Database from "better-sqlite3";

// Schema
// CREATE TABLE usernames (
//   username TEXT PRIMARY KEY,
//   install_id TEXT NOT NULL,
//   registered_at TEXT NOT NULL,
//   last_seen_at TEXT NOT NULL
// );

export function createDb(dataDir: string): Database.Database { ... }
```

--------------------------------

### Run Sandboxed Profile

Source: https://github.com/kzahel/yepanywhere/blob/main/docker/README.md

Starts the container with full network access and restricted filesystem/privileges.

```bash
docker compose -f docker/docker-compose.yml up
```

--------------------------------

### Build and Run the Relay

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/relay/README.md

Commands to compile the relay package and start the server process.

```bash
pnpm --filter @yep-anywhere/relay build
node packages/relay/dist/index.js
```

--------------------------------

### Session Metadata Example

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/055-session-catchup-unbounded-fetch.md

Example of session metadata associated with the problematic request.

```text
sessionId: 019f28d9-2dff-7dd2-8326-4b0e6093aed4
provider: codex
project: /Users/kgraehl/code/mclone
```

--------------------------------

### Run Cold-Index Performance Harness

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/038-codex-session-index-memory.md

Start the development server with performance logging enabled to validate memory and parsing metrics.

```bash
SESSION_INDEX_LOG_PERF=true \
CODEX_READER_LOG_PARSE=true \
YEP_DATA_DIR=/tmp/ya-cold-index-streaming \
pnpm --filter @yep-anywhere/server dev
```

--------------------------------

### Install Cloudflare Tunnel

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/project/remote-access.md

Commands to install the cloudflared utility on macOS and Linux systems.

```bash
# macOS
brew install cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
```

--------------------------------

### Agent Markdown Examples

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/009-local-resource-link-routing.md

Examples of Markdown syntax used by agents to reference local files.

```md
![probe](C:/tmp/playbox-zero-g-compare.png)
```

```md
[probe json](C:/tmp/playbox-zero-g-compare.json)
```

--------------------------------

### Build and run from source

Source: https://github.com/kzahel/yepanywhere/blob/main/README.md

Clone the repository and build the project locally to run it from source.

```bash
git clone https://github.com/kzahel/yepanywhere.git
cd yepanywhere
pnpm install
pnpm build
pnpm start
```

--------------------------------

### JSONL Persisted Events Example

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/research/debug-session-events-report.md

Example of the JSONL format used for storing durable user and assistant messages on disk.

```jsonl
{"type":"queue-operation","operation":"dequeue","timestamp":"2026-01-05T18:06:56.908Z",...}
{"type":"user","uuid":"94c1c05b-...","message":{"content":"What is 2+2? Answer briefly."},...}
{"type":"assistant","uuid":"4a2eadbf-...","message":{"content":[{"type":"text","text":"4"}]},...}
```

--------------------------------

### Deploy and Launch Android Device Server

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/project/device-bridge.md

Commands to push the APK to an Android device and start the server process via ADB.

```bash
adb -s <serial> push yep-device-server.apk /data/local/tmp/
adb -s <serial> shell CLASSPATH=/data/local/tmp/yep-device-server.apk \
    app_process /system/bin com.yepanywhere.DeviceServer
adb -s <serial> forward tcp:27183 tcp:27183   # video
adb -s <serial> forward tcp:27184 tcp:27184   # control
```

--------------------------------

### Initialize State and DOM References

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/client/public/debug-streaming.html

Sets up the application state and retrieves necessary DOM elements for the streaming interface.

```javascript
let isStreaming = false; let abortController = null; const currentBlocks = new Map(); let maxBlockIndex = -1; let totalEvents = 0; // DOM refs const blocksContainer = document.getElementById('streaming-blocks'); const pendingEl = document.getElementById('streaming-pending'); const consoleLog = document.getElementById('console-log'); const markdownInput = document.getElementById('markdown-input'); const speedSlider = document.getElementById('speed'); const chunkSizeSlider = document.getElementById('chunk-size'); const speedValue = document.getElementById('speed-value'); const chunkSizeValue = document.getElementById('chunk-size-value'); const streamBtn = document.getElementById('stream-btn'); const stopBtn = document.getElementById('stop-btn'); const resetBtn = document.getElementById('reset-btn'); const clearLogBtn = document.getElementById('clear-log-btn'); const statusStreaming = document.getElementById('status-streaming'); const statusBlocks = document.getElementById('status-blocks'); const statusEvents = document.getElementById('status-events');
```

--------------------------------

### GET /api/project-queue

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/023-project-queue.md

Retrieve the global project queue.

```APIDOC
## GET /api/project-queue

### Description
Retrieve the global project queue.

### Method
GET

### Endpoint
/api/project-queue
```

--------------------------------

### GET /stats

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/relay/README.md

Returns an HTML rendering of telemetry samples.

```APIDOC
## GET /stats

### Description
Provides an HTML rendering of collected telemetry samples.

### Method
GET

### Endpoint
/stats
```

--------------------------------

### Build and Verify Desktop Application

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/012-desktop-surfaces-and-server-output.md

Commands to build the desktop package and verify the Rust source code.

```bash
pnpm --filter @yep-anywhere/desktop build
cd packages/desktop/src-tauri && cargo check
```

--------------------------------

### GET /api/projects/:projectId/queue

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tactical/023-project-queue.md

Retrieve the queue for a specific project.

```APIDOC
## GET /api/projects/:projectId/queue

### Description
Retrieve the queue for a specific project.

### Method
GET

### Endpoint
/api/projects/:projectId/queue

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project.
```

--------------------------------

### Build Site Changes

Source: https://github.com/kzahel/yepanywhere/blob/main/CLAUDE.md

Build the marketing site located in the site directory.

```bash
cd site && npm run build   # Astro check + build (or: pnpm site:build from root)
```

--------------------------------

### Launch Device Server Manually via ADB

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/android-device-server/README.md

Push the APK to the device, start the process using app_process, and forward the communication port.

```bash
adb -s <serial> push app/build/outputs/apk/release/yep-device-server.apk /data/local/tmp/yep-device-server.apk
adb -s <serial> shell CLASSPATH=/data/local/tmp/yep-device-server.apk app_process /system/bin com.yepanywhere.DeviceServer
adb -s <serial> forward tcp:27183 tcp:27183
```

--------------------------------

### GET /health

Source: https://github.com/kzahel/yepanywhere/blob/main/packages/relay/README.md

Returns the current health status of the relay service.

```APIDOC
## GET /health

### Description
Returns the service status, uptime, number of waiting connections, and active pairs.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Current service status
- **uptime** (number) - Service uptime in seconds
- **waiting** (number) - Number of waiting connections
- **pairs** (number) - Number of active pairs
```

--------------------------------

### GET /debug/sessions

Source: https://github.com/kzahel/yepanywhere/blob/main/docs/tasks/2025-01-05-debug-api-spec.md

List all active sessions with their current process information.

```APIDOC
## GET /debug/sessions

### Description
List all active sessions with process info.

### Method
GET

### Endpoint
/debug/sessions

### Response
#### Success Response (200)
- **sessions** (array) - List of active sessions

#### Response Example
{
  "sessions": [
    {
      "sessionId": "5af3eb9b-c0b3-4318-a314-3d9b99e3cfa9",
      "processId": "abc-123",
      "state": "idle",
      "messageCount": 173,
      "streamEventCount": 7992,
      "startedAt": "2025-01-05T10:00:00Z",
      "idleSince": "2025-01-05T10:30:00Z"
    }
  ]
}
```