Server SDKs

Pillar's server SDKs let you define tools that run on your backend instead of in the browser. When a user triggers a server tool through the co-pilot, Pillar Cloud sends a webhook to your server, your handler runs with full access to your database and APIs, and the result flows back to the conversation.

When to use server tools

Use server-side tools when the operation requires:

Database access — look up records, update state, run queries
Secret credentials — third-party API keys, payment processing
Business logic — pricing calculations, permission checks, data validation
Side effects — sending emails, creating invoices, provisioning resources

Use client-side tools when the operation is purely in the browser — navigating to a page, opening a modal, or copying text to the clipboard.

Client vs server tools

	Client tools	Server tools
Where they run	In the user's browser	On your backend
Defined with	`usePillarTool` / `defineTool` in frontend code	`defineTool` (TypeScript) or `@pillar.tool()` (Python)
Access to	DOM, app state, router	Database, APIs, secrets
Registration	CLI sync scans your frontend code	SDK registers via HTTP to Pillar Cloud
Confirmation	User clicks a button in the panel	`ConfirmationResponse` renders a channel-appropriate UI
Tool types	`navigate`, `trigger_tool`, `query`, `inline_ui`, etc.	Single type — just an `execute` handler
Framework	React, Vue, Angular, Vanilla JS	Express, Fastify, Hono, Next.js, Django, Flask, FastAPI

How it works

You define tools with defineTool (TypeScript) or @pillar.tool() (Python)
The SDK registers your tools with Pillar Cloud on startup
A user asks something like "Look up sarah@acme.com"
Pillar Cloud matches the intent to your lookup_customer tool
Pillar Cloud sends a signed webhook to your server
Your execute handler runs and returns a result
The result appears in the conversation

All webhook payloads are signed with HMAC-SHA256 so you can verify they come from Pillar. See Webhook Security for details.

Available SDKs

Language	Package	Install
TypeScript / Node.js	`@pillar-ai/server`	`npm install @pillar-ai/server`
Python	`pillar-ai-server`	`pip install pillar-ai-server`

Both SDKs have the same capabilities — tools, confirmations, signature verification, and framework adapters. Pick the one that matches your backend.

Next steps

Quickstart — Install the SDK and define your first tool
Defining Tools — Schemas, guidance, timeouts, and return values
Framework Integration — Mount the webhook handler in your framework