### Install Onyx Craft with Quickstart Script Source: https://github.com/onyx-dot-app/onyx/blob/main/web/src/app/craft/README.md Use this script to install Onyx Craft, which configures the environment for building applications. It sets necessary environment variables and downloads overlay configurations. ```bash 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 ``` -------------------------------- ### Onyx File Store Usage Example Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/file_store/README.md Demonstrates how to get the default file store, initialize it, save, check, read, and delete files. Includes examples for reading with temporary files and retrieving file metadata. ```python from onyx.file_store.file_store import get_default_file_store from onyx.configs.constants import FileOrigin # Get the configured file store file_store = get_default_file_store() # Initialize the storage backend (creates bucket if needed) file_store.initialize() # Save a file with open("example.pdf", "rb") as f: file_id = file_store.save_file( content=f, display_name="Important Document.pdf", file_origin=FileOrigin.OTHER, file_type="application/pdf", file_metadata={"department": "engineering", "version": "1.0"} ) # Check if a file exists exists = file_store.has_file( file_id=file_id, file_origin=FileOrigin.OTHER, file_type="application/pdf" ) # Read a file file_content = file_store.read_file(file_id) # Read file with temporary file (for large files) file_content = file_store.read_file(file_id, use_tempfile=True) # Get file metadata file_record = file_store.read_file_record(file_id) # Get file with MIME type detection file_with_mime = file_store.get_file_with_mime_type(file_id) # Delete a file file_store.delete_file(file_id) ``` -------------------------------- ### Opencode Serve Listener Setup Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/opencode-serve-test-report.md Command to start opencode serve with specific logging and port configuration. Uses setsid and nohup for background execution within a pod. ```bash setsid sh -c "... nohup opencode serve ... install.sh && chmod +x install.sh && ./install.sh ``` -------------------------------- ### Quick Start: Stage and Run Docker Compose Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/docker/docker-compose-overview.md This script stages the necessary Docker Compose files and environment templates, runs the installer, configures essential environment variables, and brings up the Onyx Craft stack using Docker Compose. ```bash # 1. Stage compose files (they're not in any release tag yet). WT=/path/to/onyx/checkout # this repo, checked out on a branch with the Docker backend mkdir -p ~/onyx_data/deployment ~/onyx_data/data/nginx cp "$WT"/deployment/docker_compose/docker-compose.yml ~/onyx_data/deployment/ cp "$WT"/deployment/docker_compose/docker-compose.craft.yml ~/onyx_data/deployment/ cp "$WT"/deployment/docker_compose/env.template ~/onyx_data/deployment/ cp "$WT"/deployment/data/nginx/app.conf.template ~/onyx_data/data/nginx/ cp "$WT"/deployment/data/nginx/run-nginx.sh ~/onyx_data/data/nginx/ # 2. Run installer in --local mode with craft. bash "$WT"/deployment/docker_compose/install.sh --local --include-craft # 3. Fix the .env (existing-env install path skips these; see "Required env vars" below). cat >> ~/onyx_data/deployment/.env <<'ENV' ENABLE_CRAFT=true SANDBOX_BACKEND=docker SANDBOX_API_SERVER_URL=http://host.docker.internal:3001 HOST_PORT=3001 ENV # 4. If running an unreleased PR (e.g. opencode-serve), build the backend # and sandbox images locally and point .env at them. See "Running an # unreleased PR" below. # 5. Bring it up. (cd ~/onyx_data/deployment && docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d) # 6. Configure an LLM provider via Admin UI at http://localhost:3001 # (Craft will fail with "No default LLM model found" until you do this.) ``` -------------------------------- ### Install Opal Package Source: https://github.com/onyx-dot-app/onyx/blob/main/web/lib/opal/README.md Install the Opal package using bun. This is the primary installation step. ```sh bun add @onyx-ai/opal ``` -------------------------------- ### Build and Start Production Application Source: https://github.com/onyx-dot-app/onyx/blob/main/examples/widget/README.md Build the application for production and start the production server. These commands prepare the widget for deployment. ```bash bun run build bun run start ``` -------------------------------- ### POST /session/setup Endpoint Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/infra/sandbox-daemon-expansion.md Used to create a new session workspace. It handles directory creation, template copying, dependency installation, symlinking skills, writing configuration files, and optionally starting the Next.js server. ```http POST /session/setup Body: { "session_id": "", "nextjs_port": , "agents_md": "", "opencode_json": "", "org_info": {"AGENTS.md": "...", "user_identity_profile.txt": "...", "organization_structure.json": "..."} | null, "copy_outputs_template": true, "npm_install": true, "symlink_managed_skills": true } → Creates session dir, copies outputs template, runs npm install, symlinks .opencode/skills → /workspace/managed/skills, writes AGENTS.md + opencode.json + org_info/*, starts Next.js if port given. → 200 {"status": "ok"} or 4xx/5xx on validation/setup failure. ``` -------------------------------- ### Install Node Dependencies for Frontend Source: https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md Navigate to the 'onyx/web' directory and install frontend dependencies using bun. ```bash bun install ``` -------------------------------- ### Copy Example Environment File Source: https://github.com/onyx-dot-app/onyx/blob/main/widget/README.md Copies the example environment file to .env for self-hosted builds. This should be done from the widget directory. ```bash # Copy example env file (for self-hosted builds) cp .env.example .env ``` -------------------------------- ### Install Onyx Helm Chart Source: https://github.com/onyx-dot-app/onyx/blob/main/deployment/terraform/modules/aws/README.md Installs or upgrades the Onyx Helm chart. This example disables MinIO and configures the chart to use an existing service account for S3 access, assuming IRSA was set up by the EKS module. ```bash helm upgrade --install onyx /path/to/onyx/deployment/helm/charts/onyx \ --namespace onyx \ --set minio.enabled=false \ --set serviceAccount.create=false \ --set serviceAccount.name=onyx-s3-access ``` -------------------------------- ### Install Kind, Helm, and Telepresence Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/dev/local-kubernetes.md Installs necessary tools for local Kubernetes development. Ensure Docker Desktop is running with sufficient resources. ```bash brew install kind helm kubectl curl -fLo /opt/homebrew/bin/telepresence \ https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-arm64 chmod +x /opt/homebrew/bin/telepresence ``` -------------------------------- ### Install ODS Binary Locally Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Install the ODS binary locally using 'go install .'. This outputs the binary to your GOPATH, typically '~/go/bin/ods'. ```shell ~/go/bin/ods --version ``` -------------------------------- ### Usage Example Source: https://github.com/onyx-dot-app/onyx/blob/main/web/lib/opal/src/core/animations/README.md Example demonstrating how to use the Hoverable.Root and Hoverable.Item components together. ```APIDOC ## Usage Example ### Description This example shows how to set up a hoverable group using `Hoverable.Root` and `Hoverable.Item`. ### Code ```tsx import { Hoverable } from "@opal/core";
Appears on hover
``` ``` -------------------------------- ### Usage Examples Source: https://github.com/onyx-dot-app/onyx/blob/main/web/lib/opal/src/layouts/content/README.md Illustrative examples of how to use the Content component with different configurations. ```APIDOC ## Usage Examples ### ContentXl — headline, icon on top ```tsx import { Content } from "@opal/layouts"; import SvgSearch from "@opal/icons/search"; ``` ### ContentXl — with more icons ```tsx import { Content } from "@opal/layouts"; import SvgSearch from "@opal/icons/search"; import SvgStar from "@opal/icons/star"; import SvgLock from "@opal/icons/lock"; ``` ### ContentLg — section, icon inline ```tsx import { Content } from "@opal/layouts"; import SvgSearch from "@opal/icons/search"; ``` ### ContentMd — with icon and description ```tsx import { Content } from "@opal/layouts"; import SvgSearch from "@opal/icons/search"; ``` ### ContentMd — title only (no icon, no description) ```tsx import { Content } from "@opal/layouts"; ``` ### Editable title ```tsx import { Content } from "@opal/layouts"; import SvgSearch from "@opal/icons/search"; save(newTitle)} /> ``` ``` -------------------------------- ### Start Onyx Model Server Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Starts the model server. Ensure the environment is correctly configured. ```shell ods backend model_server ``` -------------------------------- ### Install Python Dependencies Source: https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md Install the required Python dependencies for the backend using uv sync. ```bash uv sync ``` -------------------------------- ### Rendered AVAILABLE_SOURCES_SECTION Example Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/search/search-requirements.md This example shows how the {{AVAILABLE_SOURCES_SECTION}} placeholder in SKILL.md.template is rendered for a user with multiple connected sources. ```markdown - google_drive — Internal docs, meeting notes, draft specs - slack — Channels: #eng, #sales, #incidents, #product (+ DMs the user is in) - linear — Engineering tickets across teams: backend, frontend, infra - (user_uploads) — Files the user has attached to this session, under `attachments/` ``` -------------------------------- ### Install Onyx with a single command Source: https://github.com/onyx-dot-app/onyx/blob/main/README.md This command downloads and executes the Onyx installation script. Ensure you review scripts from the internet before execution. ```bash curl -fsSL https://onyx.app/install_onyx.sh | bash ``` -------------------------------- ### Install OpenAPI Generator Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/tests/integration/README.md Install the necessary tool to generate the Python client for integration tests. ```sh brew install openapi-generator ``` -------------------------------- ### Start Local Monitoring Stack Source: https://github.com/onyx-dot-app/onyx/blob/main/profiling/README.md Navigate to the profiling directory and start the Docker Compose services to launch Prometheus and Grafana. ```bash cd profiling/ docker compose up -d ``` -------------------------------- ### Start Onyx API Server Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Starts the FastAPI backend server. Ensure the environment is correctly configured. ```shell ods backend api ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/onyx-dot-app/onyx/blob/main/desktop/README.md Installs all project dependencies for the Onyx desktop application. This command should be run from the repository root. ```bash # From the repo root bun install ``` -------------------------------- ### Example Onyx CLI Search Command Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/search/4-craft-search.md Example of how to use the onyx-cli to search company knowledge. Use the returned JSON's 'document' field for citation. ```bash onyx-cli search "" ``` -------------------------------- ### Opal Component Usage Example Source: https://github.com/onyx-dot-app/onyx/blob/main/web/lib/opal/README.md Example demonstrating how to import and use components like Button, Text, and layouts from Opal. Ensure necessary imports are present. ```tsx import { Button, Text } from "@onyx-ai/opal/components"; import { Content } from "@onyx-ai/opal/layouts"; import SvgPlus from "@onyx-ai/opal/icons/plus"; function MyComponent() { return ( ); } ``` -------------------------------- ### Launch Interactive Chat TUI Source: https://github.com/onyx-dot-app/onyx/blob/main/cli/README.md Start the interactive chat TUI for a human-friendly interface. The first launch will guide you through the setup process. ```shell onyx-cli chat ``` -------------------------------- ### Replace npm install with bun install Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/bun-node-modules-dedup.md Updates setup scripts to use 'bun install --frozen-lockfile' instead of 'npm install'. This change is applied in both Kubernetes and Docker manager setup scripts. ```bash cd outputs/web && bun install --frozen-lockfile ``` -------------------------------- ### Setup and Run Craft Development Environment Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/2026-05-21-nuke-local-sandbox-manager.md This command sequence is used to set up the craft development environment, including deleting any existing cluster, ensuring a clean slate, and then provisioning the environment. It is used to verify the one-shot setup process. ```bash kind delete cluster --name onyx-dev rm .vscode/.env.k8s make craft-up ``` -------------------------------- ### Start Devcontainer Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Starts the Onyx devcontainer, pulling the latest image if necessary. Requires the devcontainer CLI to be installed. ```shell ods dev up ``` -------------------------------- ### Typical Workflow for Benchmarking Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/sandbox/image-and-spinup.md Build the current dev image and a candidate image, then run the benchmark script to compare them. This workflow assumes you have 'make' and 'docker' installed. ```bash # 1. Build current dev image + a candidate you want to compare make craft-sandbox-image # onyxdotapp/sandbox:dev docker build --build-arg ENABLE_SKILLS=false \ -t onyxdotapp/sandbox:candidate \ backend/onyx/server/features/build/sandbox/kubernetes/docker # 2. Benchmark both (3 reps each scenario by default) REPS=3 backend/onyx/server/features/build/sandbox/kubernetes/scripts/bench-sandbox-spinup.sh \ onyxdotapp/sandbox:dev \ onyxdotapp/sandbox:candidate ``` -------------------------------- ### Action ID Hierarchy Example Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/external-apps/action-policies.md Illustrates the layered fallback mechanism for determining an action ID, starting from semantic actions and falling back to generic HTTP actions. ```text semantic (slack.channel.read) → generic service (slack.http.post) → generic http (unknown.http.post) ``` -------------------------------- ### Component Organization Example Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/web/AGENTS.md Illustrates a recommended file structure for organizing reusable UI components within the 'components/' directory. ```tree components/ ├── dashboard/ # Feature-specific components │ ├── stats-card.tsx │ ├── activity-feed.tsx │ └── recent-items.tsx ├── charts/ # Chart components │ ├── line-chart.tsx │ ├── bar-chart.tsx │ └── pie-chart.tsx ├── data/ # Data display components │ ├── data-table.tsx │ ├── filter-bar.tsx │ └── sort-controls.tsx └── layout/ # Layout components ├── header.tsx ├── sidebar.tsx └── footer.tsx ``` -------------------------------- ### CLI Client Initialization Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/search/3-cli-search-command.md Illustrates the common pattern for initializing the client configuration and API client in CLI commands. ```go config, client, err := requireClient() ``` -------------------------------- ### Get full API response from Onyx search Source: https://github.com/onyx-dot-app/onyx/blob/main/cli/internal/embedded/SKILL.md Retrieve the complete API response, including citation IDs, for programmatic use. This example pipes the output to jq to extract titles. ```bash onyx-cli search --raw "API documentation" | jq '.results[].title' ``` -------------------------------- ### Start Mock Services Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/tests/integration/README.md Launch the mock connector server container required for specific integration tests. ```sh docker compose -f docker-compose.mock-it-services.yml -p mock-it-services-stack up -d ``` -------------------------------- ### Install Rust Source: https://github.com/onyx-dot-app/onyx/blob/main/desktop/README.md Installs the latest stable version of Rust using the official installation script. Ensure to source the environment variables after installation. ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env ``` -------------------------------- ### Build and Install ODS Wheel Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Build and install the wheel package for ODS using 'uv pip install .'. ```shell uv pip install . ``` -------------------------------- ### Install Python 3.11 on macOS Source: https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md Installs Python 3.11 using Homebrew. Ensure Homebrew is installed first. ```bash brew install python@3.11 ``` -------------------------------- ### Using setupUser() for User Interactions Source: https://github.com/onyx-dot-app/onyx/blob/main/web/tests/README.md Demonstrates the correct usage of `setupUser()` for simulating user interactions, highlighting its advantage of automatic `act()` wrapping compared to `userEvent.setup()`. ```typescript // ✅ Correct - Automatic act() wrapping const user = setupUser(); await user.click(button); await user.type(input, "text"); // ❌ Wrong - Manual act() required, verbose const user = userEvent.setup(); await act(async () => { await user.click(button); }); ``` -------------------------------- ### Update CONTRIBUTING.md for Craft Setup Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/2026-05-21-nuke-local-sandbox-manager.md Replace references to `SANDBOX_BACKEND=local` with instructions to use `docs/dev/local-kubernetes.md` and `make craft-up` for Craft work. ```markdown for Craft work, see `docs/dev/local-kubernetes.md` ``` ```markdown make craft-up ``` -------------------------------- ### Install Onyx CLI with uv Source: https://github.com/onyx-dot-app/onyx/blob/main/cli/README.md Install the onyx-cli package using uv, a fast Python package installer. This can be an alternative to pip for managing dependencies. ```shell uv pip install onyx-cli ``` -------------------------------- ### Run Frontend Development Server Source: https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md Start the frontend development server. Navigate to the 'onyx/web' directory before running this command. ```bash bun run dev ``` -------------------------------- ### Run Frontend Development Server Source: https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md Starts the Next.js development server using bun scripts from `web/package.json`. No directory change is required. ```shell ods web dev ``` -------------------------------- ### Install Playwright Dependencies Source: https://github.com/onyx-dot-app/onyx/blob/main/web/README.md Installs the necessary dependencies for Playwright end-to-end testing. ```bash bunx playwright install ``` -------------------------------- ### Install Dependencies Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/sandbox/kubernetes/docker/skills/image-generation/SKILL.md Install the required Python packages for the image generation script. ```bash pip install google-genai Pillow ``` -------------------------------- ### Install Pre-commit Hooks Source: https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md Set up pre-commit hooks for the backend, which include ruff and ruff format. ```bash uv run pre-commit install ``` -------------------------------- ### Initialize and Save Presentation Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/build/sandbox/kubernetes/docker/skills/pptx/pptxgenjs.md Basic setup for creating a new presentation, defining layout, and saving the file. ```javascript const pptxgen = require("pptxgenjs"); let pres = new pptxgen(); pres.layout = 'LAYOUT_16x9'; // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE' pres.author = 'Your Name'; pres.title = 'Presentation Title'; let slide = pres.addSlide(); slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" }); pres.writeFile({ fileName: "Presentation.pptx" }); ``` -------------------------------- ### Original firewall-init.sh entrypoint Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/features/approvals/phase-5-docker.md The original script uses 'gosu' to execute the entrypoint, which results in the agent process running with no capabilities in Effective/Permitted sets, but the Bounding set still contains CAP_NET_ADMIN. ```bash exec gosu 1000:1000 "$@" ``` -------------------------------- ### Install Onyx CLI Skill Source: https://github.com/onyx-dot-app/onyx/blob/main/cli/README.md Installs the bundled SKILL.md for AI coding agents to discover the CLI. Use flags to customize installation location, copying behavior, or target specific agents. ```shell onyx-cli install-skill onyx-cli install-skill --global onyx-cli install-skill --copy onyx-cli install-skill --agent claude-code ``` -------------------------------- ### Install Dependencies with uv sync Source: https://github.com/onyx-dot-app/onyx/blob/main/backend/requirements/README.md Installs project dependencies using uv sync. The default command installs shared, backend, dev, and ee dependencies. Specific groups can be targeted or excluded. ```bash uv sync ``` ```bash uv sync --no-default-groups --group backend ``` ```bash uv sync --no-default-groups --group model_server ``` -------------------------------- ### Bring up Onyx Craft services Source: https://github.com/onyx-dot-app/onyx/blob/main/docs/craft/docker/docker-compose-overview.md Navigate to the deployment directory and use Docker Compose to start the Onyx Craft services defined in the specified compose files. ```bash (cd ~/onyx_data/deployment && docker compose -f docker-compose.yml -f docker-compose.craft.yml up -d) ``` -------------------------------- ### Button Usage Examples Source: https://github.com/onyx-dot-app/onyx/blob/main/web/lib/opal/src/components/buttons/button/README.md Examples showing primary, icon-only, secondary, and interaction-controlled buttons. ```tsx import { Button } from "@opal/components"; import { SvgPlus, SvgArrowRight } from "@opal/icons"; // Primary button with label // Icon-only button (renders as a square) // Interaction override (e.g. inside a popover trigger)