Psyche

Self-hosted AI chat client with full control over providers, models, files, and deployment

Psyche combines a React frontend, a Fastify API, PostgreSQL persistence, provider management, streaming replies, attachments, and a deployment layout designed for self-hosted use.

Overview

Psyche is a self-hosted AI chat client for people who want direct control over providers, models, conversations, attachments, storage, and deployment.

Instead of relying on a hosted workspace, Psyche gives you a single-user environment with an installable web app, a configurable API backend, database-backed persistence, folder-based conversation organization, and support for multiple provider types from one interface.

Features

• Self-hosted single-user workspace
• OpenAI-compatible provider support
• Anthropic provider support
• In-app provider and model management
• Folder tree for organizing conversations
• Streaming responses with in-place thinking state
• Image and file attachments
• Markdown and code rendering
• PWA-ready frontend for desktop and mobile install

Tech Stack

• Frontend: Next.js 15, React 18, TypeScript, Tailwind CSS 4, Radix UI
• Backend: Fastify 5, TypeScript, Prisma 6, Zod
• Database: PostgreSQL 16
• Runtime and tooling: Node.js, npm workspaces, Docker Compose, PM2, Nginx
• Model providers: OpenAI-compatible APIs, Anthropic Messages API

Project Structure

apps/
  api/                     Fastify API service
  web/                     Next.js frontend application
deploy/
  nginx/                   Nginx site config
research/
  chatgpt-style-20260314/  UI and interaction notes
docker-compose.yml         Local PostgreSQL service
ecosystem.config.cjs       PM2 production config

Quick Start

1. Install dependencies.

npm install

2. Create environment files.

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

3. Start PostgreSQL.

docker compose up -d

4. Generate Prisma client and push the schema.

npm run prisma:generate
npm run prisma:push

5. Start the API and web app.

npm run dev

Default local URLs after startup:

• Web: http://localhost:5173
• API: http://localhost:8787

Environment Variables

apps/api/.env

• PORT: API port, default 8787
• DATABASE_URL: PostgreSQL connection string
• WEB_ORIGIN: allowed frontend origin
• PUBLIC_API_BASE_URL: public API base URL
• JWT_SECRET: session signing secret
• COOKIE_SECRET: cookie signing secret
• ENCRYPTION_KEY: provider key encryption secret
• SELF_HOSTED_MODE: self-hosted single-user mode switch
• FILE_STORAGE_DIR: upload storage path
• MAX_UPLOAD_BYTES: max upload size in bytes
• MAX_UPLOAD_FILES: max files per upload request
• OPENAI_COMPATIBLE_DEFAULT_BASE_URL: default OpenAI-compatible endpoint

apps/web/.env

• NEXT_PUBLIC_API_BASE_URL: frontend API base URL

Current Capabilities

• Connection profiles store provider name, base URL, key, default model, and discovered models
• Conversations support rename, delete, folder nesting, and folder-level creation
• Attachments currently support common images plus pdf, txt, and md
• The assistant response area shows an in-place thinking state before streamed text arrives
• The web app can be installed as a PWA for a more app-like workflow

Production Notes

Build both apps:

npm run build

Run the API with PM2:

pm2 start ecosystem.config.cjs

Nginx example config is provided at:

deploy/nginx/psyche.0xpsyche.me.conf

The default production layout in this repository serves:

• frontend static files from apps/web/dist
• API traffic through /api/

Use Cases

• Self-hosting a private AI workspace with your own provider keys
• Managing multiple model backends from one UI
• Organizing long-running chats inside folders instead of flat lists
• Handling images, PDFs, and text attachments in the same workspace

Security Note

Psyche is intended for self-hosted operation and stores provider credentials in your own stack.

Before exposing it beyond a trusted environment, make sure you review:

• database and file storage access
• secret generation for JWT_SECRET, COOKIE_SECRET, and ENCRYPTION_KEY
• reverse proxy policy and HTTPS termination
• host-level process, filesystem, and network permissions

Repository

• GitHub: https://github.com/githubbzxs/psyche