Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/felixdotgo/querybox/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers building QueryBox for development and production.

​
Development Mode

The fastest way to develop QueryBox is using the built-in hot-reload mode: 
wails3 dev
This starts the application with:
  • Frontend hot-reload - Changes to Vue components reflect immediately
  • Backend hot-reload - Go changes trigger an automatic rebuild
  • Debug mode - Additional logging and development tools enabled
The development server runs on a configurable port (default: 9245).

​
Custom Port

To use a different port: 
# Using Task
task dev VITE_PORT=3000

# Or directly
wails3 dev -config ./build/config.yml -port 3000

​
Building Plugins

Plugins must be built before running the application: 
task build:plugins
This script:
  1. Creates the bin/plugins/ directory if it doesn’t exist
  2. Builds all executables in the plugins/ directory
  3. Outputs binaries to bin/plugins/

​
Cross-Platform Plugin Builds

Build plugins for different platforms using Go’s cross-compilation: 
# Build for Windows
GOOS=windows GOARCH=amd64 task build:plugins

# Build for Linux
GOOS=linux GOARCH=amd64 task build:plugins

# Build for macOS (Intel)
GOOS=darwin GOARCH=amd64 task build:plugins

# Build for macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 task build:plugins
Windows builds automatically get the .exe suffix.

​
Plugin Discovery

At startup, the application:
  1. Copies plugins from bin/plugins/ to the user config directory
  2. Scans both locations for available plugins
  3. User directory plugins take precedence over bundled ones
Plugins are discovered automatically within 2 seconds of being added to either directory.

​
Production Builds

Build a production-ready executable: 
wails3 build
The production binary is placed in bin/ and includes:
  • Optimized frontend bundle
  • Compiled Go backend
  • Embedded assets
  • Platform-specific packaging

​
Platform-Specific Builds

Build for your current platform: 
task build
Or target a specific platform: 
# Build for the current OS
task build

# The task automatically delegates to the correct platform:
# - task windows:build (Windows)
# - task darwin:build (macOS)
# - task linux:build (Linux)

​
Package for Distribution

Create a distributable package: 
task package
This:
  1. Builds all plugins
  2. Builds the main application
  3. Creates a platform-specific package:
    • Windows: .exe installer
    • macOS: .app bundle and .dmg
    • Linux: .AppImage or .deb
Packages are output to the build/bin/ directory.

​
Server Mode

QueryBox can run as a headless HTTP server without the GUI:

​
Build Server Mode

task build:server

​
Run Server Mode

task run:server

​
Docker Server Mode

Build and run QueryBox in a Docker container: 
# Build Docker image
task build:docker

# Run Docker container
task run:docker
The server mode is useful for:
  • Remote database management
  • CI/CD integrations
  • Headless environments
  • API-only deployments

​
Creating a New Plugin

To create a new database plugin:

​
1. Copy the Template

cp -r plugins/template plugins/your-plugin-name

​
2. Implement the Plugin Interface

Edit plugins/your-plugin-name/main.go and implement the four required commands:
  • info - Return plugin metadata (name, version, type) 
    // Return JSON with name, version, and database type
  • authforms - Return auth form definitions for the UI 
    // Define form fields for connection credentials
  • exec - Execute a query and return results 
    // Parse query, execute against database, return results
  • connection-tree - Return a browsable object hierarchy 
    // Return databases, tables, columns, etc.

​
3. Build the Plugin

task build:plugins

​
4. Test the Plugin

The running app will discover the new plugin automatically (no restart needed if already running). For detailed plugin development, see the Plugin System documentation.

​
Protobuf Code Generation

If you modify .proto files, regenerate the Go code: 
task proto:generate
This requires:
  • protoc (Protocol Buffer compiler)
  • protoc-gen-go (Go code generator)
  • protoc-gen-go-grpc (Go gRPC code generator)
Generated files are placed in rpc/contracts/plugin/v1/.

​
Build Scripts

QueryBox uses Task for build automation. Available tasks:
TaskDescription
task devRun in development mode with hot-reload
task buildBuild for current platform
task packageCreate distributable package
task build:pluginsBuild all plugins
task build:serverBuild in server mode (no GUI)
task run:serverRun server mode
task build:dockerBuild Docker image
task run:dockerRun Docker container
task proto:generateGenerate code from .proto files
task setup:dockerSetup Docker for cross-compilation
View all available tasks: 
task --list

​
Troubleshooting

​
Plugin Not Discovered

  1. Verify binary is in bin/plugins/ or user config directory
  2. Ensure binary is executable: chmod +x bin/plugins/your-plugin
  3. Check the Plugins window for errors in PluginInfo.LastError
  4. Use the Rescan button in the Plugins window to re-probe

​
Build Fails on Windows

Ensure you have a C compiler installed:

​
Frontend Build Errors

Clear the build cache: 
rm -rf frontend/node_modules frontend/dist
wails3 dev

​
Next Steps

Testing

Learn how to run and write tests

Plugin System

Deep dive into plugin architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us