Skip to main content

​
Prerequisites

Before you begin, ensure your system meets these requirements:

System Requirements

  • OS: Linux, macOS, or Windows
  • RAM: 4GB minimum (8GB recommended)
  • Disk: 2GB available space
  • Network: Internet connection for component streaming

Development Tools

  • Rust: 1.70+ (for building from source)
  • Cargo: Rust’s package manager
  • Git: For cloning the repository

​
Installation

​
Build and Install from Source

# Clone the repository
git clone https://github.com/opnbook/taho.git
cd taho

# Install both taho-host and taho CLI
cargo install --path taho-host --force
cargo install --path taho-cli --force

# Verify installation
taho --help
This installs both binaries to ~/.cargo/bin/ (ensure this directory is in your PATH).
The taho CLI automatically locates and manages the taho-host runtime binary.

​
Your First TAHO Service

Let’s start the TAHO runtime and invoke a service using the REST API.
1

Start TAHO Runtime

Start the TAHO runtime using the CLI:
# Start with default configuration
taho start

# You should see the TAHO ASCII logo and:
# HTTP API available at http://localhost:9481
By default, TAHO starts on port 9481. You can configure this in config.toml or via environment variables.
To see detailed logs during startup:
taho start --verbose
2

Configure Component Repository

TAHO loads components from configured repositories. Create or edit config.toml in the project root:
# Component repository URLs
repo_urls = [
  "file:///path/to/your/components",
  "https://github.com/yourusername/taho-components"
]

# HTTP server configuration
[http]
port = 9481

# TLS configuration (optional)
[http]
tls_enable = false
For development, use file:// URLs pointing to local directories containing your .wasm component files.
3

Invoke a Service

With TAHO running and components loaded, invoke a service method:
# Invoke a service method using curl
curl -X POST http://localhost:9481/api/services/{domain}/{service}/invoke/{method} \
  -H "Content-Type: application/json" \
  -d '{"input": "your data here"}'
For example, if you have a hello service in the example domain with a greet method:
curl -X POST http://localhost:9481/api/services/example/hello/invoke/greet \
  -H "Content-Type: application/json" \
  -d '{"name": "World"}'
Expected response:
{
  "result": "Hello, World!"
}
4

Manage Services

Use the API to manage running services:
# Restart a service with new configuration
curl -X POST http://localhost:9481/api/services/example/hello/restart \
  -H "Content-Type: application/json" \
  -d '{"config": "updated configuration"}'

# Gracefully stop a service
curl -X PUT http://localhost:9481/api/services/example/hello/quiesce

# Reload all components
curl -X POST http://localhost:9481/api/reload

​
Understanding the Service Endpoint Pattern

TAHO uses a consistent URL pattern for service invocation: 
POST /api/services/{domain}/{service}/invoke/{method}
  • domain: The domain/namespace of your component (e.g., example, myapp)
  • service: The service name (e.g., hello, calculator)
  • method: The method to invoke (e.g., greet, add)
The request body contains the method parameters as JSON.

​
Configuration

​
Configuration File

TAHO uses a layered configuration system:
  1. Built-in defaults
  2. Repository config (taho/config.toml)
  3. User config (platform-specific config directory)
  4. Environment variables (prefix: TAHO__)
View your merged configuration: 
# View as TOML
taho config

# View as JSON
taho config --format json

​
Environment Variables

Override configuration via environment variables: 
# Set HTTP port
export TAHO__HTTP__PORT=8080

# Configure repository URLs
export TAHO__REPO_URLS="file:///path/to/components https://github.com/user/repo"

# Enable TLS
export TAHO__HTTP__TLS_ENABLE=true

# Start with custom configuration
taho start

​
Key Configuration Options

[http]
port = 9481
tls_enable = false
tls_port = 9443

​
Building a Simple Service Component

Here’s a minimal example of a TAHO service component in Rust:
1

Create Component Interface

Define your service interface using WIT (WebAssembly Interface Types):
// hello.wit
package example:hello@0.1.0;

interface greet {
  greet: func(name: string) -> string;
}

world hello-service {
  export greet;
}
2

Implement the Service

Create the Rust implementation:
// src/lib.rs
wit_bindgen::generate!({
    world: "hello-service",
    exports: {
        "example:hello/greet": Component,
    },
});

struct Component;

impl exports::example::hello::greet::Guest for Component {
    fn greet(name: String) -> String {
        format!("Hello, {}!", name)
    }
}
And Cargo.toml:
[package]
name = "hello-service"
version = "0.1.0"
edition = "2021"

[dependencies]
wit-bindgen = "0.16.0"

[lib]
crate-type = ["cdylib"]

[package.metadata.component]
package = "example:hello"
3

Build the Component

# Install required tools
rustup target add wasm32-wasi
cargo install cargo-component

# Build the component
cargo component build --release
Your compiled component will be at: target/wasm32-wasi/release/hello_service.wasm
4

Deploy to TAHO

Copy your component to a repository location:
# Copy to local file repository
cp target/wasm32-wasi/release/hello_service.wasm /path/to/components/

# Or commit to git repository
git add target/wasm32-wasi/release/hello_service.wasm
git commit -m "Add hello service"
git push
Then reload TAHO to pick up the new component:
curl -X POST http://localhost:9481/api/reload

​
Common Commands

​
CLI Commands

# Start the runtime
taho start                      # Show ASCII logo, hide logs
taho start --verbose            # Show all logs
taho start --logo-off           # Suppress logo

# View configuration
taho config                     # Display as TOML
taho config --format json       # Display as JSON

​
API Endpoints

# Invoke a service method
POST /api/services/{domain}/{service}/invoke/{method}

# Restart a service with new config
POST /api/services/{domain}/{service}/restart

# Gracefully stop a service
PUT /api/services/{domain}/{service}/quiesce

# Reload all components
POST /api/reload

​
Troubleshooting

Make sure ~/.cargo/bin is in your PATH:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Check that:
  1. Your component is in a configured repository path
  2. The component file has a .wasm extension
  3. The component implements the correct WIT interface
View logs with:
taho start --verbose
Change the port via configuration:
export TAHO__HTTP__PORT=8080
taho start
Verify the service is loaded:
# Check logs for component loading
taho start --verbose

# Ensure the URL pattern matches: /api/services/{domain}/{service}/invoke/{method}

​
What’s Next?

Component Development

Learn to build production-ready WebAssembly service components

Architecture Overview

Understand how TAHO loads and executes components

Configuration Guide

Deep dive into TAHO’s configuration system

API Reference

Complete API documentation with examples
Need help? Join our Discord community for support and to share what you’re building with TAHO!