QadEng Documentation

QadEng is a native macOS cloud development platform. Built entirely in Swift for Apple Silicon Macs.

Key Services

• Functions - Serverless execution using Apple Containers
• Storage - Object storage with bucket management and website hosting
• Database - NoSQL key-value tables with query support
• Queues - Message queuing with visibility timeout
• Topics - Pub/Sub messaging for event distribution
• Parameters - Secret/config store (SecureString uses Keychain)
• API Gateway - HTTP routing and proxying to functions
• Event Mappings - Queue-to-function triggers
• Apps - Bundled resource deployments

Installation

Requirements

• macOS 26.0+ (Tahoe)
• Apple Silicon Mac

Download

QadEng will be available on the Mac App Store. Get notified when we launch.

Quick Start

Once QadEng is running, the platform auto-starts on app launch. The API endpoint is available at:

http://localhost:7566

Check Health

curl http://localhost:7566/_qadeng/health

Create Your First App

Create a directory with a qadeng.yaml manifest and add it to QadEng:

mkdir -p my-app/functions/hello
cd my-app

# Create manifest
cat > qadeng.yaml << 'EOF'
name: my-app
description: My first QadEng app
EOF

# Create function config
cat > functions/hello/function.yaml << 'EOF'
runtime: python3.12
handler: main.handler
memory: 256
timeout: 30
EOF

# Create function code
cat > functions/hello/main.py << 'EOF'
def handler(event, context):
    return {
        "statusCode": 200,
        "body": "Hello from QadEng!"
    }
EOF

Then add and enable the app via the UI or API:

# Add the app
curl -X POST http://localhost:7566/apps \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/my-app"}'

# Enable the app
curl -X PUT http://localhost:7566/apps/my-app/enable

# Invoke the function
curl -X POST http://localhost:7566/functions/hello/invoke

Apps System

Apps are the primary way to manage resources in QadEng. An app is a directory containing related cloud resources that are deployed together.

App Structure

my-app/
├── qadeng.yaml           # App manifest (required)
├── functions/            # Function directories
│   └── my-func/
│       ├── function.yaml # Runtime, handler config
│       └── main.py       # Function code
├── storage/              # Bucket directories
│   └── my-bucket/
│       ├── _bucket.yaml  # Website config (optional)
│       └── ...files      # Bucket objects
├── database/             # Table JSON files
│   └── my-table.json
├── queues/               # Queue YAML files
│   └── my-queue.yaml
├── parameters/           # Parameter YAML files
│   └── config.yaml
├── api-gateway/          # Gateway definitions
│   └── api.yaml
└── mappings/             # Event source mappings
    └── mappings.yaml

Manifest Files

qadeng.yaml

The root manifest file defines the app:

name: my-app
description: A sample application

function.yaml

Each function requires a configuration file:

runtime: python3.12    # python3.10-12, nodejs18-20, go1.21-22, java17/21
handler: main.handler  # file.function
memory: 256           # MB (or use memorySize)
timeout: 30           # seconds

# Optional fields:
description: My function description
warm: true            # Keep container warm
environment:          # Environment variables
  API_KEY: my-key
  DEBUG: "true"

Functions

Serverless functions run in Apple Containers with support for Python, Node.js, Go, and Java runtimes.

Supported Runtimes

Python Function Example

def handler(event, context):
    # event contains the request payload
    name = event.get('name', 'World')

    return {
        'statusCode': 200,
        'headers': {'Content-Type': 'application/json'},
        'body': {'message': f'Hello, {name}!'}
    }

Node.js Function Example

exports.handler = async (event, context) => {
    const name = event.name || 'World';

    return {
        statusCode: 200,
        headers: { 'Content-Type': 'application/json' },
        body: { message: `Hello, ${name}!` }
    };
};

Storage

Object storage with bucket management and optional static website hosting.

Website Hosting

Enable website hosting for a bucket by adding a _bucket.yaml file:

website:
  enabled: true
  indexDocument: index.html
  errorDocument: error.html

Website-enabled buckets are accessible via subdomain-style URLs or path-style URLs.

Database

NoSQL key-value tables with flexible schemas and query support.

Table Definition

{
  "tableName": "users",
  "keySchema": {
    "partitionKey": "id",
    "sortKey": "email"
  },
  "items": [
    {"id": "1", "email": "user@example.com", "name": "John"}
  ]
}

Queues

Message queuing with visibility timeout support. Messages can trigger functions via event source mappings.

Queue Definition

name: tasks
visibilityTimeout: 30
maxReceiveCount: 3

Topics

Pub/Sub messaging for event distribution. Publish once, deliver to multiple subscribers.

Topic Definition

name: notifications
subscriptions:
  - protocol: function
    endpoint: email-handler
  - protocol: queue
    endpoint: notifications-queue

API Gateway

HTTP routing and proxying to functions. Define routes and integrate with your serverless functions.

Gateway Definition

name: main-api
description: Main API gateway
routes:
  - path: /users
    method: GET
    function: list-users
  - path: /users/{id}
    method: GET
    function: get-user
  - path: /users
    method: POST
    function: create-user

Parameters

Secret and configuration store. SecureString parameters are encrypted using macOS Keychain.

Parameter Definition

parameters:
  - name: /app/config/api-key
    type: SecureString
    value: my-secret-key
  - name: /app/config/debug
    type: String
    value: "true"

Parameter Types

Event Mappings

Event source mappings connect queues to functions, automatically triggering function invocations when messages arrive.

Mapping Definition

mappings:
  - eventSource: queue
    sourceArn: tasks-queue
    functionName: task-processor
    batchSize: 10
    enabled: true
  - eventSource: queue
    sourceArn: notifications-queue
    functionName: notification-handler
    batchSize: 1
    enabled: true

Configuration Options

Containers

QadEng uses Apple Containers for function execution. The Containers tool lets you manage containers directly.

Container Management

The Containers view in QadEng lets you:

• View running containers and their status
• Inspect container details and logs
• Stop or kill running containers
• Manage container images
• Monitor resource usage

Warm Executor Pools

QadEng maintains warm executor pools for frequently-used function configurations:

• Up to 10 warm executors per function configuration
• 10-minute TTL for idle warm executors
• Automatic cleanup of expired executors
• Instant cold starts for pooled configurations

AI Assistant

QadEng includes a built-in AI assistant powered by Apple Intelligence for natural language interaction with your services.

Capabilities

• Create, update, and manage functions using natural language
• Query database tables and view results
• Send and receive queue messages
• Manage storage buckets and objects
• Configure API Gateway routes
• View logs and debug issues

Usage

Access the AI Assistant by clicking the assistant button in the bottom-right corner of the app, or use the keyboard shortcut. The assistant is context-aware and provides relevant tools based on the current view.

Logs

QadEng provides comprehensive logging for all platform activity.

HTTP Traffic Logs

View all API requests to QadEng with:

• Request method, path, and status code
• Request and response headers
• Request and response bodies
• Timing information
• Service routing information

System Logs

View internal platform logs including:

• Service startup and shutdown events
• Function invocation logs
• Container lifecycle events
• Error messages and warnings

Filtering & Export

Filter logs by method, status code, service, or search text. Export logs as JSON or CSV for external analysis.

Terminal

The built-in terminal provides direct access to interact with QadEng services via the command line.

Features

• Direct shell access for debugging
• Run curl commands against the API
• View container logs
• Execute scripts and automation

API Reference

Base URL: http://localhost:7566

Health Endpoints

Functions API

Storage API

Database API

Queues API

Topics API

API Gateway API

Event Mappings API

Parameters API

Containers API

Apps API

Examples

QadEng includes sample apps and examples to help you get started:

• Sample apps with functions, storage, and database
• Full demo applications
• API usage examples

Examples will be included with the app when it launches on the Mac App Store.