Skip to content

fix: Make Echo seamless to run locally #760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ledgerpilot wants to merge 2 commits into
base: master
Choose a base branch
from
+40 −117
Draft

fix: Make Echo seamless to run locally #760

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5efc21
fix: address issue #597 — Make Echo seamless to run locally
ledgerpilot Apr 8, 2026
f426aba
fix: address issue #597 — Make Echo seamless to run locally
ledgerpilot Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 17 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,127 +1,27 @@
![Echo Header](./imgs/header_gif.gif)

<div align="center">

# Echo

</div>

<div align="center">

[![Discord](https://img.shields.io/discord/1382120201713352836?style=flat&logo=discord&logoColor=white&label=Discord)](https://discord.gg/merit)
![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/merit_systems)
[![GitHub Repo stars](https://img.shields.io/github/stars/Merit-Systems/echo?style=social)](https://github.com/Merit-Systems/echo)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

</div>

**User-pays AI infrastructure. Drop in Echo, users pay for their own usage—you never front costs.**

Skip the hard choice between fronting API costs, high-friction BYOK flows, or building billing from scratch.

[Read the docs](https://echo.merit.systems/docs) | [Live demo](https://echo-next-image.vercel.app/) | [Read our announcement](https://www.merit.systems/blog/echo)

## The Problem

Building AI apps forces you to pick your poison:

| Approach | Developer Cost | User Experience | Revenue Model |
| ------------------ | ----------------------- | ---------------------- | ------------------------ |
| **BYOK** | None (but no revenue) | Complex key management | None |
| **Dev API Key** | Unpredictable burn rate | Simple | Need metering + billing |
| **Bill End Users** | Weeks building infra | Simple | Auth + Stripe + metering |

Echo eliminates all three problems.

## How Echo Works

Replace your AI SDK imports with Echo. Users authenticate once, get a balance, and pay for their own usage. You set a markup and earn revenue automatically.

**Before:**

```typescript
// Option 1: Front costs yourself
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
const response = await generateText({
model: openai('gpt-5'),
'YOUR-API-KEY',
prompt: '...'
});

```

**After:**

```typescript
// Users pay, you earn markup, zero infrastructure
import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
import { generateText } from 'ai';

const { openai } = useEchoModelProviders();
const response = await generateText({
model: openai('gpt-5'),
prompt: '...',
});
```

## Quick Start

```bash
pnpx echo-start@latest
```

Creates a new app with Echo pre-configured. Live in 2 minutes.

## Why Echo?

**No hosting costs** - Users pay providers directly through Echo. You never proxy requests or front bills.

**Better UX** - One OAuth login replaces complex BYOK flows. Users get a universal balance across all Echo apps.

**Instant revenue** - Set a markup percentage. Every token generates profit automatically.

**Zero infrastructure** - No payment processing, no usage tracking, no key validation. Echo handles it all.

## Core

- [Echo Control](./packages/app/control): Next.js app for [echo.merit.systems](https://echo.merit.systems). Hosted site and api routes.
- [Echo Server](./packages/app/server): Express server for router.echo.merit.systems. Proxy for routing and metering LLM requests from clients.

## SDKs

- [Echo TS SDK](./packages/sdk/ts) Typescript SDK that all the framework specific SDKs are built on top of.
- [Echo Next.js SDK](./packages/sdk/next) SDK for simple Next.js 15+ App Router integration.
- [Echo React SDK](./packages/sdk/react) SDK for simple React client side SPA integration.

## Examples

- [Echo Next.js Example](./packages/sdk/examples/next)
- [Echo React SDK](./packages/sdk/examples/vite)

## Templates

Get started quickly with `echo-start`:
Echo is a platform designed to simplify complex system interactions and data flows, providing a seamless experience for developers and users. This repository contains the monorepo for Echo, including its core application, SDK, and various templates.

```bash
pnpx echo-start gen-ai-app
```
## 🚀 Getting Started Locally

Available templates:
This guide will help you get Echo up and running on your local machine for development and testing.

- **[next](./templates/next)** - Next.js application with Echo
- **[react](./templates/react)** - Vite React application with Echo
- **[next-chat](./templates/next-chat)** - Next.js chatbot with Echo and Vercel AI SDK
- **[assistant-ui](./templates/assistant-ui)** - Next.js with Echo and Assistant UI
- **[echo-cli](./templates/echo-cli)** - CLI tool for AI chat with Echo (API keys + crypto wallets)
### Prerequisites

Or run `npx echo-start my-app` to choose interactively.
Before you begin, ensure you have the following software installed:

**Note:** The CLI template (`echo-cli`) requires manual installation from the repository as it's a command-line tool rather than a web application. See the [templates README](./templates/README.md) for details.
* **Git**: For cloning the repository.
* [Download Git](https://git-scm.com/downloads)
* **Node.js**: Version 18.x or later is recommended.
* [Download Node.js](https://nodejs.org/en/download/)
* **pnpm**: A fast, disk-space efficient package manager.
* Install with `npm install -g pnpm`
* **Docker & Docker Compose**: For running the local database.
* [Download Docker Desktop](https://www.docker.com/products/docker-desktop/) (includes Docker Compose)

# Development
### Setup Steps

Fill out `packages/app/control/.env` and `packages/app/server/.env`. Then...
Follow these steps to get Echo running:

- `pnpm i`
- `pnpm dev`
1. **Clone the Repository**
23 changes: 23 additions & 0 deletions docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
version: '3.8'
services:
db:
image: postgres:15-alpine
restart: always
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: mysecretpassword # IMPORTANT: Use a strong, unique password for production environments!
POSTGRES_DB: echo_dev
ports:
- "5432:5432" # Expose PostgreSQL port to the host
volumes:
# Persist data to a named volume to prevent data loss on container removal
- db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d echo_dev"]
interval: 5s
timeout: 5s
retries: 5

volumes:
db_data:
driver: local