Morphic Documentation

Morphic is an AI-powered search engine featuring a generative UI that renders rich inline components (like source-credited images, grids, and headings) from a streamed JSON spec.

Key features include:

• Search Modes: Quick and Adaptive.
• Model Support: Dynamic provider detection for OpenAI, Anthropic, Google, Ollama, Vercel AI Gateway, and OpenAI-compatible providers.
• Search Providers: Tavily, SearXNG, Brave, and Exa.
• Data & Auth: Chat history stored in PostgreSQL, user authentication via Supabase Auth, guest mode, and file upload support.
• Sharing: Ability to share search results via unique URLs.

The fastest way to run Morphic locally is via Docker. This method automatically starts PostgreSQL, Redis, SearXNG, and Morphic. Using SearXNG means no additional search API key is required for basic usage.

1. Pull the latest image:

docker pull ghcr.io/miurla/morphic:latest

2. Clone the repository and configure environment:

git clone https://github.com/miurla/morphic.git
cd morphic
cp .env.local.example .env.local

3. Edit .env.local to include at least one AI provider API key (e.g., OPENAI_API_KEY).

4. Start the services:

docker compose up -d

5. Access the application at http://localhost:3000.

docker pull ghcr.io/miurla/morphic:latest

git clone https://github.com/miurla/morphic.git
cd morphic
cp .env.local.example .env.local

# After editing .env.local
docker compose up -d

By default, Docker runs in anonymous mode (ENABLE_AUTH=false), which is intended for single-user local use. To enable multi-user authentication via Supabase, you must build from source because the NEXT_PUBLIC_* variables are embedded at build time.

1. Set up a Supabase project.
2. Provide the following environment variables:
   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
   • SUPABASE_SECRET_KEY
   • ENABLE_AUTH=true
3. Build and start the containers: docker compose up -d --build

The chat-cli.ts script is a command-line interface for testing the Morphic chat API without a browser. It supports real-time SSE streaming, configurable search modes, session continuity, and message regeneration.

Requirements:

• Bun runtime
• A local development server running (bun dev)
• Valid authentication cookies in .env.local

# Using the recommended npm script
bun chat -m "Hello, how are you?"

# Direct usage
bun scripts/chat-cli.ts -m "Hello, how are you?"

Morphic uses PostgreSQL to persist chat history. If you do not configure a database, Morphic runs in a stateless mode.

To configure a database, set the DATABASE_URL in your .env.local file. You can use local PostgreSQL, Neon, or Supabase.

Note: If using Docker, the database is automatically configured and you do not need to set this variable.

After setting the connection string, run migrations to create the required tables using bun run migrate. Docker runs migrations automatically on startup.

DATABASE_URL=postgresql://user:password@localhost:5432/morphic

# After setting the URL, run migrations:
bun run migrate

To run Morphic in a development environment using bun:

1. Clone and install dependencies:

git clone https://github.com/miurla/morphic.git
cd morphic
bun install

2. Configure environment variables:

cp .env.local.example .env.local

Edit .env.local and set your required API keys, such as OPENAI_API_KEY or TAVILY_API_KEY.

3. Start the development server:

bun dev

Access the app at http://localhost:3000.

git clone https://github.com/miurla/morphic.git
cd morphic
bun install
cp .env.local.example .env.local
# Edit .env.local with API keys
bun dev

To authenticate the CLI, add your session cookies to a .env.local file in the project root using the MORPHIC_COOKIES key.

Note: Cookies typically expire after approximately 1 hour. If you encounter "User not authenticated" errors, refresh your cookies from your browser's DevTools and update the file.

MORPHIC_COOKIES="your-cookie-string-here"

You can maintain conversation continuity using a Chat ID (-c or --chat-id). To regenerate the last assistant message in a specific session, use the regenerate trigger with the corresponding message ID.

# Continue an existing chat
bun chat -c "chat_123" -m "Tell me more"

# Regenerate the last assistant message
bun chat -c "chat_123" -t regenerate --message-id "msg_456"

# Edit a user message and regenerate
bun chat -c "chat_123" -t regenerate --message-id "msg_456" -m "Tell me about machine learning instead"

To run Morphic quickly using the recommended prebuilt Docker image, pull the image, configure your environment variables, and start the services via Docker Compose.

1. Pull the latest image: docker pull ghcr.io/miurla/morphic:latest
2. Create your environment file: cp .env.local.example .env.local
3. Edit .env.local to include at least one AI provider API key (e.g., OPENAI_API_KEY).
4. Start the services: docker compose up -d
5. Access the application at http://localhost:3000.

docker pull ghcr.io/miurla/morphic:latest
cp .env.local.example .env.local
# Edit .env.local with your API keys
docker compose up -d

Morphic dynamically detects available AI providers based on the API keys provided in your .env.local file. You can select your preferred model directly from the UI model selector. Supported provider keys include:

• OPENAI_API_KEY (OpenAI)
• ANTHROPIC_API_KEY (Anthropic)
• GOOGLE_GENERATIVE_AI_API_KEY (Google)
• OLLAMA_BASE_URL (Ollama)
• AI_GATEWAY_API_KEY (Vercel AI Gateway)

File upload is disabled by default in Docker. To enable it, you must provide an externally reachable object storage configuration using the following environment variables:

• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• R2_BUCKET_NAME
• And one of: R2_ACCOUNT_ID (for Cloudflare R2) or S3_ENDPOINT (for generic S3-compatible storage).