# How to Configure Dify Chat for Single Application Mode: A Complete Guide

> Easily configure Dify Chat single application mode. Learn to set RUNNING_MODE or initialize runtime with singleApp and provide API credentials for seamless integration.

- Repository: [lexmin0412/dify-chat](https://github.com/lexmin0412/dify-chat)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To configure Dify Chat for single application mode, initialize the runtime with `singleApp` in [`packages/react-app/src/App.tsx`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/App.tsx) or set `RUNNING_MODE=singleApp` in your environment variables, then provide your Dify API credentials via the configuration drawer.**

Dify Chat supports two distinct operational modes: multi-application for managing multiple AI assistants and single-application for focusing on one dedicated chatbot. This guide covers the exact steps to switch the `lexmin0412/dify-chat` repository to single application mode, including runtime configuration, API setup, and storage backend selection.

## Understanding Single vs Multi-Application Modes

Dify Chat operates through a runtime configuration that determines how the UI behaves:

- **Multi-Application Mode**: Displays an app list page where users can switch between multiple Dify apps. Initialized with `multiApp` in the runtime config.
- **Single-Application Mode**: Hides the app list and opens one specific chatbot directly. Initialized with `singleApp`.

The switch requires only configuration changes—no codebase rewrite is necessary. The runtime always loads service implementations from `src/services/app`, choosing between `singleApp/` or `multiApp/` directories based on your initialization.

## Method 1: Configure Single Application Mode in React SPA

For the React single-page application package, you must modify the runtime initialization directly in the source code.

### Modifying the Runtime Initialization

In [`packages/react-app/src/App.tsx`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/App.tsx), locate the runtime initialization and change the argument from `'multiApp'` to `'singleApp'`:

```typescript
// packages/react-app/src/App.tsx
import { difyChatRuntimeConfig } from '@dify-chat/helpers';

// Initialize the runtime for single application mode
difyChatRuntimeConfig.init('singleApp');  // Change from 'multiApp'

```

This call configures the entire component tree to operate in single-application context. After this change, the UI will hide the application list and route users directly to the configured chat interface.

## Method 2: Configure Single Application Mode in Next.js

For the Next.js platform package, use environment variables to control the runtime mode.

Set the `RUNNING_MODE` variable in your `.env` file (copy from `packages/platform/.env.template`):

```bash

# packages/platform/.env

RUNNING_MODE=singleApp

```

The Next.js application reads this variable during initialization to determine which runtime mode to activate. This approach keeps configuration external to the codebase, making it ideal for containerized deployments.

## Setting Up API Credentials and Storage Backend

After switching the runtime mode, you must provide connection details through the configuration drawer that appears on first launch.

### API Configuration Requirements

The configuration drawer requires these mandatory fields:

- **API Base**: The root URL of your Dify server (e.g., `https://api.dify.ai/v1`)
- **API Secret**: The authorization key from your Dify console trial page
- **App Type**: Select "Chat Bot" or the appropriate application type

These values are persisted according to your selected storage strategy.

### Selecting a Storage Strategy

The runtime loads storage implementations from `src/services/app/singleApp/`. Three strategies are available:

- **static-readonly**: Hard-coded configuration, read-only. Ideal for demos where the app never changes.
- **localstorage**: Full CRUD operations using browser `localStorage`. Data remains client-side only.
- **restful**: Calls a backend API. Recommended for production deployments requiring server-side persistence.

For quick starts, the repository defaults to **localstorage**. The implementation resides in [`packages/react-app/src/services/app/singleApp/localstorage.ts`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/services/app/singleApp/localstorage.ts):

```typescript
// packages/react-app/src/services/app/singleApp/localstorage.ts
export const appConfig = {
  getApp: () => JSON.parse(localStorage.getItem('difyApp') ?? '{}'),
  setApp: (cfg: any) => localStorage.setItem('difyApp', JSON.stringify(cfg)),
  // Additional CRUD methods...
};

```

Export your chosen implementation through the service index:

```typescript
// packages/react-app/src/services/app/singleApp/index.ts
export { appConfig } from './localstorage';  // Switch to './restful' for API backend

```

To implement a custom backend, extend the abstract class `DifyAppStore` as documented in `packages/docs/docs/Latest/guide/app-config/config-single/modify-code.mdx`, then expose your implementation through the same index file.

## How UI Components Adapt to Single Application Mode

Chat UI components automatically detect the runtime mode via `difyChatRuntimeConfig`. For example, in [`packages/react-app/src/components/chatbox/app-input-form.tsx`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/components/chatbox/app-input-form.tsx), the component respects the mode through props:

```typescript
// packages/react-app/src/components/chatbox/app-input-form.tsx
// Component receives mode="single" based on runtime configuration

```

No additional code changes are required for components to adapt—the runtime configuration propagates through the helper context automatically.

## Summary

- **Switch the runtime**: Call `difyChatRuntimeConfig.init('singleApp')` in [`packages/react-app/src/App.tsx`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/App.tsx) or set `RUNNING_MODE=singleApp` in Next.js environments.
- **Configure credentials**: Provide API Base URL and Secret through the UI configuration drawer on first load.
- **Select storage**: Choose between `static-readonly`, `localstorage`, or `restful` implementations in `src/services/app/singleApp/`.
- **Implement custom backends**: Extend `DifyAppStore` and export from the service index for production persistence requirements.

## Frequently Asked Questions

### What is the difference between singleApp and multiApp modes in Dify Chat?

**singleApp** mode hides the application list page and opens one specific chatbot directly, suitable for individual users or single-purpose deployments. **multiApp** mode displays a dashboard listing all available Dify applications, designed for enterprise environments managing multiple AI assistants. The underlying code remains identical; only the runtime initialization and UI routing change.

### Where do I find the API Secret for Dify Chat configuration?

Obtain the API Secret from your Dify console. Navigate to your application's "API" section and copy the secret key from the 30-second trial page or the permanent API credentials section. This 32-character string authorizes your `dify-chat` frontend to communicate with the Dify backend services.

### Can I switch from single application mode back to multi-application mode?

Yes. Reverse the configuration change: update [`packages/react-app/src/App.tsx`](https://github.com/lexmin0412/dify-chat/blob/main/packages/react-app/src/App.tsx) to use `difyChatRuntimeConfig.init('multiApp')` or change `RUNNING_MODE` to `multiApp` in your environment variables. The UI will immediately render the application list page instead of the single chat interface. Existing storage data remains intact but may require migration if switching storage strategies simultaneously.

### How do I implement a custom storage backend for single application mode?

Implement the abstract class `DifyAppStore` defined in the project documentation, providing methods for get, set, update, and delete operations. Place your implementation in `packages/react-app/src/services/app/singleApp/` and export it from [`index.ts`](https://github.com/lexmin0412/dify-chat/blob/main/index.ts) instead of the default localstorage export. This allows integration with PostgreSQL, Redis, or any external REST API while maintaining compatibility with the single application runtime.