Sailhouse: an event-driven control platform for building and coordinating AI intelligences

Sailhouse is an event-driven infrastructure platform for developers that is centrally positioned as an "intelligence control plane". The platform is designed to help developers quickly and reliably build and release AI Agents and asynchronous applications of all kinds. While traditional intelligence development often requires complex orchestration frameworks or message queues, Sailhouse provides a lighter-weight solution. It orchestrates collaboration between multiple intelligences or services through an event-driven model that allows developers to define dynamic workflows. Whether it's a scheduled task that needs to be executed on time or a complex workflow that requires multiple steps to be processed in parallel, Sailhouse provides the tools to do so. The platform supports deployment on major cloud services such as AWS, GCP, Vercel, etc., and is independent of specific programming languages, so developers can use their own familiar technology stack for development.

Function List

• time trigger: Supports setting up timed events and Cron scheduled tasks, which can automatically trigger tasks at a specific point in the future or on a fixed cycle.
• Wait Groups: Allows combining multiple parallel tasks together (Fan-out) and waiting for all tasks to complete before triggering a new event (Fan-in), which is suitable for handling complex multi-step workflows.
• cross-platform compatibility: Sailhouse doesn't limit the environment in which the code can run, whether it's on major cloud vendors such as AWS, Azure, GCP, or Serverless platforms such as Vercel, Netlify, etc., it works fine.
• Flexible event reception mode: Both "Push" and "Pull" modes are supported. Developers can either configure an HTTP endpoint to receive push events or write a worker to actively pull events from the queue.
• Event Filtering: Allow filtering rules to be set at subscription time to receive only eligible events and avoid processing irrelevant messages.
• speed limit: You can control the rate at which events are processed to prevent downstream services from crashing due to traffic overload.

Using Help

Sailhouse is designed with the idea of simplifying the development of event-driven applications so that developers can focus on business logic without having to care about the underlying complex infrastructure. The following section describes in detail how to use the core features of Sailhouse.

Core concepts

It is important to understand three basic concepts before you use them:

1. Events:: An event is a record of something that happened in the system, such as "user completed payment" or "need to process a file". It usually contains data that describes the event.
2. Topics: Topics are categorized channels for events. Producers post specific types of events to the corresponding topics. For example, all events about code review can be posted to a topic namedcode-reviewTheme.
3. Subscriptions: Subscriptions are how consumers consume events. Consumers receive events they are interested in by subscribing to one or more topics.

Installation and Configuration

Sailhouse interacts with the user's application mainly through its officially provided SDK.

1. Register for an account: First of all, you need to register an account on Sailhouse's official website and log in to the Console.
2. Creating Applications: In the console, you need to create an application (App). After creation, the system generates a unique API Key (API Key) which is the credentials for your application to communicate with the Sailhouse service.
3. Installing the SDK: Sailhouse provides corresponding SDKs for different programming languages. take JavaScript/TypeScript for example, you can use npm or yarn to install:

   npm install @sailhouse/client
   

Basic operations: sending and receiving events

1. Publishing an Event

Sending events is pretty straightforward. First, initialize the Sailhouse client in your code, then call thepublishMethods.

Sample code (JavaScript).

import { Sailhouse } from '@sailhouse/client';
// 使用你在控制台获取的API密钥初始化客户端
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function publishReviewTask() {
await sailhouse.publish({
topic: 'security-review', // 指定要发布到的主题
data: { // 附带的数据
commitId: 'a1b2c3d4',
repo: 'my-project'
}
});
console.log('安全审查任务事件已发送。');
}
publishReviewTask();

2. Receiving Events

Sailhouse provides two ways to receive events: push (Push) and pull (Pull).

Method 1: Push Subscription
This is the simplest way to do it. You just need to provide a public HTTP(S) API endpoint (also known as a Webhook). When a new event is posted to a topic you subscribe to, Sailhouse will immediately send the event as an HTTP POST request to this endpoint of yours.

• workflow:
  1. Create an API route in your project, for example/api/webhooks/sailhouseThe
  2. Create a subscription in the Sailhouse console, select "Push" mode, and fill in your API endpoint URL.
  3. Your API endpoint will receive JSON data in a format similar to the following:

     {
     "id": "event_id_string",
     "topic": "security-review",
     "data": {
     "commitId": "a1b2c3d4",
     "repo": "my-project"
     }
     }
     

  4. Your server-side code receives the request and parses thedatafields and execute the appropriate business logic.

Way 2: Pull Subscription
If your service is located behind a firewall or does not have a fixed public IP, pull mode is a better option. Your application (often called a Worker) will actively request events from Sailhouse.

• workflow:
  1. Create a subscription in the Sailhouse console and select "Pull" mode.
  2. In your Worker code, use the SDK'spullmethod to get the event. the SDK takes care of details like long polling to simplify development.

Sample Code (JavaScript Worker):: 1.1.1.2.1

import { Sailhouse } from '@sailhouse/client';
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function processEvents() {
console.log('Worker启动，开始拉取事件...');
// 循环拉取指定订阅的事件
for await (const event of sailhouse.pull({ subscription: 'security-review-worker' })) {
try {
console.log('收到事件:', event.data);
// 在这里执行你的业务逻辑
// ...
// 任务处理完成后，确认事件已被成功处理
await event.ack();
} catch (error) {
console.error('处理事件失败:', error);
// 如果处理失败，可以选择让事件重新入队
await event.nack();
}
}
}
processEvents();

Advanced Features: Using Wait Groups

Waiting Groups is a feature of Sailhouse for coordinating multiple parallel tasks. This feature is useful when you need to make sure that a group of tasks are all completed before proceeding to the next step.

For example, a code merge request needs to go through both the Security Review and Code Style Review processes. You can usesailhouse.waitto orchestrate this workflow.

Sample code (JavaScript).

import { Sailhouse } from '@sailhouse/client';
const sailhouse = new Sailhouse({ apiKey: 'YOUR_API_KEY' });
async function startCodeReviewWorkflow() {
// `wait`方法会做两件事：
// 1. 立即将两个审查任务事件分别发送到'security-review'和'style-review'主题。
// 2. 创建一个监听器，等待这两个任务都完成后，自动向'code-review-complete'主题发送一个新事件。
await sailhouse.wait(
'code-review-complete', // 当所有任务完成后，向此主题发送事件
[
{
topic: 'security-review', // 第一个任务
data: { commitId: 'a1b2c3d4', repo: 'my-project' },
},
{
topic: 'style-review', // 第二个任务
data: { commitId: 'a1b2c3d4', repo: 'my-project' },
},
]
);
console.log('代码审查工作流已启动。');
}
startCodeReviewWorkflow();

In this way, you don't need to write your own complex state management logic to track the progress of multiple parallel tasks.

application scenario

1. AI Intelligence Body Workflow Orchestration
   Sailhouse can act as a focal point for a complex task that requires the collaboration of multiple AI intelligences with different functions. For example, an "automated report generation" task may include: data collection intelligence, data analysis intelligence, chart generation intelligence, and text writing intelligence, and Sailhouse can use the wait group function to ensure that the previous tasks are all completed before triggering the subsequent tasks, and then finally summarize all the results.
2. Asynchronous background task processing
   In web applications, certain operations (e.g., sending emails, video transcoding, generating data reports) are very time-consuming and should not be performed synchronously with user requests. Developers can publish these tasks as events to Sailhouse, which are subscribed to and processed asynchronously by the Worker service in the background. This can significantly improve application responsiveness and user experience.
3. Synchronization of planned tasks and data
   For tasks that need to be performed on a regular basis, such as backing up the database in the early hours of the day, synchronizing data from a third-party API once an hour, or sending out marketing emails to subscribers on a specific date, you can use Sailhouse's Cron Scheduled Tasks or Timed Events feature. Developers simply define the execution period and task content, and Sailhouse will make sure the task is triggered on time.

QA

1. What does Sailhouse mean by "control plane"?
   In the context of Sailhouse, the "control plane" refers to an infrastructure layer that orchestrates and manages distributed components (i.e., intelligences or services). It does not intrude into your business code, nor is it a "framework" whose rules you must follow. Instead, it provides a set of tools (e.g., event routing, timers, workflow orchestration) that allow your individual services to communicate and collaborate with each other, and you only need to focus on the logic of each service itself.
2. What programming languages and cloud platforms does Sailhouse support?
   Sailhouse is designed to be language and platform agnostic. At its core, it interacts via an HTTP API or SDK, so theoretically any language capable of sending HTTP requests can use it. Official SDKs for major languages will be provided to simplify development. In terms of deployment, your intelligences or services can run anywhere, including large cloud platforms such as AWS, GCP, Azure, serverless platforms such as Vercel, Netlify, and even local development machines.
3. What is the difference between Push and Pull subscription models and how should I choose?
   Push mode is where Sailhouse actively sends events to a URL you specify. this approach has low latency, is simple to implement, and is suitable for services with fixed public IPs (e.g. APIs deployed on servers or Serverless functions). Pull mode is where your program actively requests events from Sailhouse. This approach is more flexible and is suitable for services running in an intranet environment, development environment, or services that are not comfortable exposing public ports. If your service has limited processing power, pull mode also allows you to control the rate at which you consume events based on your own load.