README

</a>

Overview

Onyx Craft is an AI coding agent that creates web applications, documents, presentations, and more using your company's indexed knowledge. Users describe what they want in natural language, and the agent builds artifacts in an isolated sandbox environment with access to documents from connected sources like Linear, Slack, Google Drive, Confluence, and more.

For detailed documentation, visit our docs.

Key Features

• Web Applications — Build Next.js applications with React, shadcn/ui, and Recharts for interactive dashboards and tools
• Documents & Reports — Generate polished markdown documents with DOCX export
• Knowledge Integration — Access indexed documents from your connectors (Linear, Slack, Google Drive, Confluence, etc.)
• Real-time Preview — Watch the agent build with live output streaming and tool call visibility
• Session Management — Pre-provisioned sandboxes, automatic snapshots, and session restore

Quick Start

Requirements

• Onyx deployment with an LLM provider configured (Anthropic, OpenAI, etc.)

New Installations

You can install Onyx Craft using our quickstart script:

curl -fsSL https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.sh > install.sh \
  && chmod +x install.sh \
  && ./install.sh --include-craft

This will:

• Set ENABLE_CRAFT=true and SANDBOX_BACKEND=docker in the .env file
• Pin IMAGE_TAG to the Craft-enabled backend image (Node.js + opencode CLI baked in)
• Download and layer in the docker-compose.craft.yml overlay so api_server / background can talk to the Docker socket
• Create the dedicated onyx_craft_sandbox bridge network used to isolate sandbox containers

Existing Deployments

Re-run the installer with --include-craft on top of an existing deployment — it patches the .env, pulls down the craft overlay, and recreates the relevant containers. Setting ENABLE_CRAFT=true by hand without re-running the installer leaves the Docker socket unmounted and sandboxes will fail to provision.

How It Works

1. User visits /craft/v1 — A sandbox is pre-provisioned in the background
2. User describes what they want — Message is sent to the OpenCode agent
3. Agent builds artifacts — Uses company knowledge and uploaded files
4. Live preview shows output — Next.js app, markdown, or other artifacts
5. User iterates or downloads — Request changes or export finished work

Technical Architecture

Sandbox Backends

Craft supports two sandbox backends controlled by SANDBOX_BACKEND:

Self-Hosted

• Filesystem-based sandboxes under SANDBOX_BASE_PATH (default: /tmp/onyx-sandboxes)
• No container isolation (process-level only)
• No automatic cleanup or snapshots
• Direct file access via symlinks to user's knowledge files

Cloud (Production)

• Pod-based isolation with ClusterIP services
• S3-based snapshots for session persistence
• Automatic cleanup of idle sandboxes (default: 1 hour timeout)
• Two containers per pod:
  • sandbox — Runs OpenCode agent and Next.js preview server
  • file-sync — Sidecar for S3 file synchronization

Session Lifecycle

Sessions go through these states:

Sandbox Workspace Structure

Each session gets an isolated workspace:

$SANDBOX_ROOT/
├── files/                     # Symlink to user's knowledge files
└── sessions/
    └── {session_id}/
        ├── outputs/web/       # Next.js application
        ├── .venv/             # Python environment
        ├── .opencode/skills/  # Agent skills
        ├── attachments/       # User uploads
        ├── AGENTS.md          # Agent instructions
        └── opencode.json      # LLM configuration

Sandbox Cleanup

Idle sandboxes are cleaned up by a Celery background task:

• Trigger: Sandbox idle longer than SANDBOX_IDLE_TIMEOUT_SECONDS (default: 1 hour)
• Kubernetes: Creates snapshots of all sessions, terminates the pod, marks sandbox as "sleeping"
• Local: No automatic cleanup (sandboxes persist until manually removed)

Configuration

Key configuration categories (see source for full reference):

• Core — ENABLE_CRAFT, SANDBOX_BACKEND (local vs kubernetes)
• Lifecycle — Idle timeout (default 1 hour), max concurrent sandboxes per org (default 10)
• Kubernetes — Namespace, container image, S3 bucket for snapshots
• File uploads — Size limits (50MB per file, 20 files per session, 200MB total)
• Rate limits — Free users: 5 messages total; Paid users: 25 messages/week

Tech Stack

Frontend

• Next.js, React, TypeScript
• Zustand for state management
• shadcn/ui components

Backend

• FastAPI, SQLAlchemy, Celery
• PostgreSQL for session/sandbox metadata
• S3-compatible storage for snapshots

Agent

• OpenCode CLI with ACP (Agent Communication Protocol)
• JSON-RPC 2.0 over stdin/stdout

Sandbox Environment

• Next.js 16, React 19
• shadcn/ui, Tailwind CSS, Recharts
• Python 3.11 with numpy, pandas, matplotlib

Coming Soon

• Presentations — Create slide decks with AI-generated visuals using nanobanana
• Spreadsheets
• HTML Dashboards

Contributing

See the main CONTRIBUTING.md for guidelines.

For Craft-specific development:

1. Set ENABLE_CRAFT=true in your environment
2. Ensure templates are available at /templates/outputs and /templates/venv
3. For local development, sandboxes are created under /tmp/onyx-sandboxes

License

MIT — see LICENSE