# How to Use Onyx for Application Development: A Developer's Guide to AI-Powered Coding

> Discover how Onyx revolutionizes application development. This AI-powered platform lets developers generate and ship full web apps from company knowledge using natural language.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: how-to-guide
- Published: 2026-03-28

---

**Onyx (formerly Danswer) is an AI-driven "Craft" platform that enables developers to generate, preview, and ship complete web applications directly from company knowledge using natural language prompts, isolated sandboxes, and a FastAPI backend.**

Onyx extends beyond traditional enterprise search to offer a comprehensive **application development environment** where AI agents write executable code. By combining the onyx-dot-app/onyx repository's chat infrastructure with secure sandboxing, teams can transform internal documentation into functional Next.js applications, documents, and presentations without writing boilerplate code.

## Architectural Overview of Onyx Application Development

The platform operates through a layered architecture that separates user interaction, AI agent execution, and artifact generation. Understanding these components is essential for customizing or extending Onyx application development workflows.

### Core System Layers

**Frontend Craft UI** — Built with React and Next.js, this interface at [`web/src/app/craft/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/web/src/app/craft/README.md) accepts natural language requests and streams live agent output. It provides export actions for downloading generated applications as ZIP archives or document files.

**FastAPI Chat Endpoint** — The router defined in [`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py) (`router = APIRouter(prefix="/chat")`) receives user prompts and forwards them to the OpenCode agent. This endpoint handles session creation at `/chat/create-chat-session` and message streaming via `/chat/send-message`.

**OpenCode Agent** — This component executes the Agent Communication Protocol (ACP) inside isolated sandboxes. It calls skills for knowledge retrieval and file generation, writing output to the sandbox workspace at `$SANDBOX_ROOT/sessions/{session_id}/outputs/web`.

**Sandbox Environment** — Provides per-user, per-session isolation using either local filesystems or Kubernetes pods. The system handles automatic snapshotting to S3 and cleanup routines, as detailed in the Craft README (lines 86-103).

**Persistence Layer** — PostgreSQL stores session metadata, sandbox status, and rate-limit counters. Database models reside in `backend/onyx/db/*` and initialize during app startup in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py).

**Build API** — Exposes generated artifacts through endpoints like `GET /build/sessions/{session_id}/webapp-download` in [`backend/onyx/server/features/build/api/sessions_api.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/api/sessions_api.py), enabling both frontend downloads and external API access.

**Celery Workers** — Background processes manage idle sandbox cleanup, workspace snapshots, and vector database synchronization, ensuring resources don't persist beyond active sessions.

### Request Processing Flow

1. User accesses `https://<host>/craft/v1`, triggering FastAPI to provision or rehydrate a sandbox from S3 snapshots.
2. Natural language prompts POST to `/chat/create-chat-session`, which invokes `chat_backend.create_chat_session` to initialize the environment.
3. The OpenCode agent executes skills, queries connected knowledge bases, and writes generated files to the sandbox workspace.
4. Live preview streams incremental updates to the React frontend while the agent works.
5. Upon completion, users download artifacts via the Build API endpoint `sessions_api.download_webapp`.
6. Idle timeouts trigger Celery tasks that snapshot workspaces to S3 and terminate sandbox pods.

## Code Example: Building an App with Onyx

You can interact with Onyx application development programmatically through its REST API. The following Python example demonstrates creating a chat session, sending a generation prompt, and retrieving the resulting application:

```python
import httpx

# 1️⃣ Start a new chat session (creates a sandbox in the background)

resp = httpx.post(
    "http://localhost:3000/api/chat/create-chat-session",
    json={"model": "gpt-4o-mini"},  # any configured LLM

)
session_id = resp.json()["session_id"]

# 2️⃣ Send a natural-language request to generate a Next.js dashboard

payload = {
    "session_id": session_id,
    "message": "Create a sales dashboard that shows total revenue by month, using a bar chart. Pull data from the 'sales' connector.",
}
stream = httpx.post(
    f"http://localhost:3000/api/chat/send-message",
    json=payload,
    timeout=None,
    stream=True,
)

# 3️⃣ Stream the agent's output (the UI does this automatically)

for chunk in stream.iter_text():
    print(chunk)          # live preview lines appear here

# 4️⃣ When finished, download the generated app

zip_resp = httpx.get(
    f"http://localhost:3000/api/build/sessions/{session_id}/webapp-download"
)
with open("dashboard.zip", "wb") as f:
    f.write(zip_resp.content)
print("✅ Dashboard ZIP saved")

```

Under the hood, `POST /api/chat/send-message` routes to `chat_backend.send_message`, which streams JSON-RPC responses from the OpenCode agent. The endpoint `GET /api/build/sessions/{session_id}/webapp-download` compresses the `/outputs/web` directory from the sandbox filesystem for delivery.

## Key Source Files for Onyx Development

Developers extending Onyx application development should examine these specific implementation files:

- **[`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py)** — FastAPI application bootstrap that registers all routers, middleware, and startup logic including database initialization.

- **[`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py)** — Contains the core chat router (`/chat/*`) with route handlers for session management and agent communication.

- **[`backend/onyx/server/features/build/api/sessions_api.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/api/sessions_api.py)** — Implements build-related endpoints including the webapp download functionality and sandbox reset operations.

- **[`web/src/app/craft/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/web/src/app/craft/README.md)** — Human-readable documentation covering Craft platform architecture, sandbox backends (self-hosted vs. cloud), and session lifecycle management.

- **[`backend/onyx/server/features/build/api/api.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/api/api.py)** — Top-level `/build` router that aggregates sub-routers for sessions, messages, and user library management.

- **`backend/onyx/worker/docfetching/`** — Celery worker implementations that maintain connector synchronization, providing the knowledge base the OpenCode agent queries during code generation.

## Getting Started with Onyx App Generation

To begin using Onyx for application development in your environment:

1. **Deploy Onyx** using the official installation script:
   ```bash
   curl -fsSL https://onyx.app/install_onyx.sh | bash
   ```

2. **Enable Craft mode** by setting `ENABLE_CRAFT=true` in your `.env` configuration file.

3. **Access the interface** at `http://localhost:3000/craft/v1` — the UI automatically provisions an isolated sandbox upon first interaction.

4. **Generate applications** through the web interface or by integrating the Python API client shown above.

5. **Export artifacts** using the download button in the UI or by calling the `/build/sessions/{session_id}/webapp-download` endpoint directly.

The sandbox architecture ensures every generated application runs in an isolated container or temporary folder, preventing code execution from affecting the host system while maintaining audit trails through PostgreSQL session logs.

## Summary

- **Onyx application development** centers on the Craft platform, which transforms natural language into executable web applications using AI agents.
- The architecture separates concerns between FastAPI endpoints ([`chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/chat_backend.py)), isolated sandbox environments, and background Celery workers.
- Generated code resides in temporary sandboxes at `$SANDBOX_ROOT/sessions/{session_id}/outputs/web` before export via the Build API.
- Developers interact with the system through REST endpoints (`/chat/create-chat-session`, `/chat/send-message`) or the React-based Craft UI.
- All sandbox executions are isolated per-user and per-session, with automatic S3 snapshotting and resource cleanup.

## Frequently Asked Questions

### What is the Onyx Craft platform?

The Craft platform is Onyx's integrated development environment that enables AI-driven application generation. It consists of a React frontend for natural language input, FastAPI endpoints for session management, and isolated sandboxes where the OpenCode agent writes and executes code based on company knowledge connectors.

### How does Onyx isolate generated applications?

Onyx uses sandbox environments that provide per-user, per-session isolation through either local filesystem containers or Kubernetes pods. Each sandbox operates within `$SANDBOX_ROOT/sessions/{session_id}/`, ensuring generated code never executes on the host system. Celery workers automatically snapshot idle sessions to S3 and terminate resources after timeout periods.

### Can I download and deploy apps created with Onyx?

Yes. Generated applications can be exported as ZIP archives via the `GET /build/sessions/{session_id}/webapp-download` endpoint implemented in [`backend/onyx/server/features/build/api/sessions_api.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/api/sessions_api.py). The downloaded package contains standard Next.js source files that can be deployed to any hosting platform supporting React applications.

### What backend technologies power Onyx application development?

The platform runs on a FastAPI backend ([`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py)) with PostgreSQL for persistence and Celery for background task processing. The OpenCode agent operates inside isolated sandboxes orchestrated through the chat endpoints in [`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py), while the Craft frontend provides the development interface at `web/src/app/craft/`.