WASM Components - TrailBase

Overview

TrailBase supports WebAssembly (WASM) components for extending server functionality. The CLI provides commands to add, remove, list, and update WASM components.

Component Management

Component References

WASM components can be referenced in three ways:

string

First-party component name from the official registry.Format: namespace/component-name (e.g., trailbase/auth_ui)Must contain only alphanumeric characters, _, -, or /

string

HTTPS URL pointing to a .wasm or .zip file.Format: https://example.com/component.wasmOnly HTTPS is supported for security reasons

string

Local filesystem path to a .wasm or .zip file.Format: ./path/to/component.wasm or /absolute/path/component.zip

Adding Components

components add

Install a WASM component from a name, URL, or local path.

trail components add <REFERENCE>

string

required

Component reference (name, URL, or path).

trail components add trailbase/auth_ui

# Output:
# Downloading https://github.com/trailbaseio/trailbase/releases/download/v0.1.0/trailbase_v0.1.0_wasm_auth_ui.zip
# Added: ["./traildepot/wasm/auth_ui_component.wasm"]

trail components add https://example.com/custom_component.wasm

# Output:
# Downloading https://example.com/custom_component.wasm
# Added: ["./traildepot/wasm/custom_component.wasm"]

trail components add https://example.com/components.zip

# Output:
# Downloading https://example.com/components.zip
# Added: ["./traildepot/wasm/component1.wasm", "./traildepot/wasm/component2.wasm"]

trail components add ./my_component.wasm

# Output:
# Added: ["./traildepot/wasm/my_component.wasm"]

trail components add /path/to/components.zip

# Output:
# Added: ["./traildepot/wasm/component1.wasm", "./traildepot/wasm/component2.wasm"]

Components are installed to <data-dir>/wasm/ directory and are automatically loaded on server startup.

Installation process:

Download/read component file(s)
Extract (if ZIP archive)
Validate WASM component format
Copy to <data-dir>/wasm/
Return list of installed files

First-party components are version-matched to your TrailBase installation. The URL template automatically uses your TrailBase version.

Removing Components

components remove

Remove an installed WASM component.

trail components remove <REFERENCE>

string

required

Component reference. Can be a name or local path. URLs are not supported for removal.

trail components remove trailbase/auth_ui

# Output:
# Removed: ["./traildepot/wasm/auth_ui_component.wasm"]

trail components remove ./traildepot/wasm/my_component.wasm

# Output:
# Removed: ["./traildepot/wasm/my_component.wasm"]

This permanently deletes the component file(s) from disk. The operation cannot be undone.

URLs cannot be used for removal. Use the component name (for first-party components) or the local path instead.

Listing Components

components list

List all available first-party components from the official registry.

trail components list

Example output:

Components:

trailbase/auth_ui

This shows components available for installation, not currently installed components. Use components installed to see installed components.

components installed

List all currently installed components with their interfaces.

trail components installed

Example output:

./traildepot/wasm/auth_ui_component.wasm - interfaces: [
  {
    "name": "auth-ui",
    "namespace": "trailbase",
    "version": "0.1.0",
    "worlds": [
      "auth-ui"
    ],
    "interfaces": [
      "login",
      "register",
      "reset-password"
    ]
  }
]

./traildepot/wasm/custom_component.wasm - interfaces: [
  {
    "name": "custom-api",
    "namespace": "example",
    "version": null,
    "worlds": [
      "api-handler"
    ],
    "interfaces": [
      "handle-request"
    ]
  }
]

Output structure:

string

Component package name.

string

Component namespace. First-party components use trailbase, custom components use custom namespaces.

string | null

Semantic version of the component, if specified.

string[]

List of WASI worlds the component implements.

string[]

List of interfaces exposed by the component.

The output filters out wasi and root namespaces, showing only application-relevant interfaces.

Updating Components

components update

Update all installed first-party components to the latest version matching your TrailBase installation.

trail components update

Example output:

Updated : ["./traildepot/wasm/auth_ui_component.wasm"]
Skipping "./traildepot/wasm/custom_component.wasm", not a first-party component

Update process:

Scan <data-dir>/wasm/ for installed components
Identify first-party components by filename
Download latest version for each
Replace existing files
Skip custom/third-party components

Only first-party components from the official registry are updated. Custom components must be updated manually.

Components are replaced in-place. If the download fails partway through, you may need to reinstall manually.

Component Structure

WASM Component Format

TrailBase uses WebAssembly Component Model (WASI Preview 2):

component.wasm
├── Package metadata
│   ├── Name
│   ├── Namespace
│   └── Version
├── Worlds
│   └── World definitions
└── Interfaces
    ├── Imports (what the component needs)
    └── Exports (what the component provides)

Component Lifecycle

Installation - Component copied to <data-dir>/wasm/
Discovery - TrailBase scans wasm/ directory on startup
Loading - Components are loaded into WASM runtime
Execution - Components respond to requests based on their interfaces
Unloading - Components are unloaded on server shutdown

Runtime Configuration

Configure WASM runtime via CLI options:

trail run \
  --runtime-threads 4 \
  --runtime-root-fs /var/lib/trailbase/fs

integer

Number of WASM isolates/workers. Defaults to CPU count.

string

Sandboxed filesystem root for WASM components.

First-Party Components

trailbase/auth_ui

Pre-built authentication UI component. Installation:

trail components add trailbase/auth_ui

Features:

Login page
Registration page
Password reset flow
Email verification
OAuth provider buttons

Interfaces:

login - Render login page
register - Render registration page
reset-password - Render password reset page

More first-party components will be added in future releases. Check the registry with trail components list.

Custom Components

Creating Custom Components

Custom WASM components must implement WASI interfaces:

Define interfaces using WIT (WebAssembly Interface Types)
Implement in your language (Rust, Go, C, etc.)
Compile to WASM Component using wasm-tools
Install via CLI

Example WIT definition:

package example:custom-api@0.1.0;

world api-handler {
  export handle-request: func(path: string) -> result<string, string>;
}

Component Requirements

requirement

Must use WASI Component Model (not core WASM modules).

requirement

Must be .wasm file or .zip containing .wasm files.

requirement

Must export at least one interface that TrailBase can invoke.

requirement

Runs in sandboxed environment with limited filesystem access.

Troubleshooting

Component Won’t Load

Error: Component file exists but isn’t loaded Solutions:

# Check component is valid WASM
trail components installed

# Verify file format
file traildepot/wasm/component.wasm
# Should show: WebAssembly (wasm) binary module

# Check server logs for WASM errors
trail run --stderr-logging

Download Fails

Error: Failed to download component Causes:

Network connectivity issues
Invalid URL
Component not available for your TrailBase version

Solutions:

# Check TrailBase version
trail --version

# Try manual download
curl -L https://github.com/trailbaseio/trailbase/releases/download/v0.1.0/component.zip -o component.zip

# Install from local file
trail components add ./component.zip

Version Mismatch

Error: Component loads but doesn’t work correctly Cause: Component version doesn’t match TrailBase version Solution:

# Update all first-party components
trail components update

# Or reinstall specific component
trail components remove trailbase/auth_ui
trail components add trailbase/auth_ui

Permission Denied

Error: Permission denied when adding component Solutions:

# Check wasm directory permissions
ls -la traildepot/wasm/

# Fix permissions
chmod 755 traildepot/wasm/

# Retry installation
trail components add component.wasm

Component Conflicts

Error: Two components with same filename Solution:

# List installed components
trail components installed

# Remove conflicting component
trail components remove ./traildepot/wasm/duplicate.wasm

# Reinstall desired component
trail components add correct-component.wasm

Advanced Usage

Component Development Workflow

Step-by-step: Develop and test custom component

# 1. Create WIT interface definition
cat > component.wit <<EOF
package example:api@0.1.0;

world handler {
  export process: func(input: string) -> string;
}
EOF

# 2. Implement in Rust (or your preferred language)
cargo component new my_component

# 3. Build WASM component
cargo component build --release

# 4. Install for testing
trail components add ./target/wasm32-wasi/release/my_component.wasm

# 5. Test with TrailBase
trail run --dev

# 6. Iterate: make changes and reinstall
cargo component build --release
trail components remove ./traildepot/wasm/my_component.wasm
trail components add ./target/wasm32-wasi/release/my_component.wasm

Packaging Components for Distribution

Step-by-step: Create distributable component package

# 1. Build component
cargo component build --release

# 2. Create ZIP package
cd target/wasm32-wasi/release/
zip my_component.zip my_component.wasm

# 3. Include documentation
zip -u my_component.zip README.md LICENSE

# 4. Upload to hosting
# Users can then install with:
trail components add https://example.com/my_component.zip

Managing Multiple Component Versions

Managing component versions across environments

# Development: use local development version
trail components add ./dev/component-dev.wasm

# Staging: use released version
trail components add https://cdn.example.com/component-v1.2.0.wasm

# Production: use first-party or stable URL
trail components add trailbase/auth_ui

# Pin to specific version via URL
trail components add https://github.com/example/releases/download/v1.0.0/component.wasm

Batch Component Operations

Install multiple components at once

# Create list of components
cat > components.txt <<EOF
trailbase/auth_ui
https://example.com/component1.wasm
./local/component2.wasm
EOF

# Install all
while read -r component; do
  echo "Installing $component..."
  trail components add "$component"
done < components.txt

# Verify all installed
trail components installed

Component Security

Sandboxing

WASM components run in a sandboxed environment:

No network access by default
Limited filesystem access (only --runtime-root-fs)
No system calls outside WASI
Memory isolation between components
CPU/memory limits enforced by runtime

Trusted Components

First-party components from trailbase/* namespace:

Built and signed by TrailBase team
Reviewed for security
Version-matched to TrailBase release
Automatically updated via components update

Third-Party Components

Third-party components run with the same privileges as first-party components. Only install components from trusted sources.

Before installing third-party components:

Review source code if available
Check developer reputation
Test in development environment first
Monitor resource usage
Review WASM interfaces with components installed

Component API Reference

WASI Interfaces

TrailBase provides these WASI interfaces to components:

interface

Sandboxed filesystem access within --runtime-root-fs.

interface

Cryptographically secure random number generation.

interface

Access to system clocks for timestamps.

interface

Standard I/O streams.

TrailBase Interfaces

TrailBase-specific interfaces for components:

interface

HTTP request handling (in development).

interface

Database access (in development).

Component API is under active development. Check documentation for the latest available interfaces.

​Overview

​Component Management

​Component References

​Adding Components

​components add

​Removing Components

​components remove

​Listing Components

​components list

​components installed

​Updating Components

​components update

​Component Structure

​WASM Component Format

​Component Lifecycle

​Runtime Configuration

​First-Party Components

​trailbase/auth_ui

​Custom Components

​Creating Custom Components

​Component Requirements

​Troubleshooting

​Component Won’t Load

​Download Fails

​Version Mismatch

​Permission Denied

​Component Conflicts

​Advanced Usage

​Component Development Workflow

​Packaging Components for Distribution

​Managing Multiple Component Versions

​Batch Component Operations

​Component Security

​Sandboxing

​Trusted Components

​Third-Party Components

​Component API Reference

​WASI Interfaces

​TrailBase Interfaces

Overview

Component Management

Component References

Adding Components

components add

Removing Components

components remove

Listing Components

components list

components installed

Updating Components

components update

Component Structure

WASM Component Format

Component Lifecycle

Runtime Configuration

First-Party Components

trailbase/auth_ui

Custom Components

Creating Custom Components

Component Requirements

Troubleshooting

Component Won’t Load

Download Fails

Version Mismatch

Permission Denied

Component Conflicts

Advanced Usage

Component Development Workflow

Packaging Components for Distribution

Managing Multiple Component Versions

Batch Component Operations

Component Security

Sandboxing

Trusted Components

Third-Party Components

Component API Reference

WASI Interfaces

TrailBase Interfaces