Life Savor Engineering Blog

Welcome to the Life Savor Engineering Blog

2025-05-16T00:00:00.000Z

We're launching this blog to share what we're building, how it works, and what we've learned along the way.

Life Savor is a local-first AI platform. Your agent runs on your device — your data stays with you. We believe AI should be private, fast, and extensible. This blog is where we'll unpack the technical decisions behind that vision.

What to Expect

We'll be writing about:

How the agent runtime works under the hood
Building skills, assistants, and model components
The developer SDK and marketplace ecosystem
Infrastructure, deployment, and platform engineering
Lessons learned shipping cross-platform software

Whether you're a developer building on the platform or just curious about how local AI agents work, we hope you'll find something useful here.

First up: a look at how the Life Savor runtime actually executes your AI workloads.

How the Life Savor Runtime Works

2025-05-14T00:00:00.000Z

The Life Savor agent is a single binary that runs on your machine. It connects to the platform, manages AI models, executes skills, and keeps everything private by default. Here's how it all fits together.

Zero Built-In Models

The agent ships with no model providers baked in. Every model — whether it's GPT-4o via API or a local LLaMA running on your GPU — is delivered as an installable component from the marketplace.

This means the base agent is small and fast to install. You add only the capabilities you need.

The Component Architecture

When you install a model component, it registers with the agent's Integration Registry. The registry tracks each provider's lifecycle: registration, health status, capabilities, and routing.

When you send a message to your agent, the Inference Bridge routes your request to the right model provider based on what's installed and healthy. If you have a local model loaded, it goes there. If you're using a cloud API, it routes through the gateway.

You → Agent → Inference Bridge → Registered Model Provider → Response

Three Ways to Run a Model

Model components follow one of three patterns:

Pattern	How it works	Example
API Gateway	Routes through the Life Savor API for centralized billing	GPT-4o, Claude, Gemini
Local	Runs on your hardware via PyTorch or ONNX Runtime	LLaMA 3, Mistral 7B, Phi-3
BYOK	Uses your own API key, calls the vendor directly	GPT-4o-BYOK, Claude-BYOK

Local Model Execution

For local models, the agent includes a dual-runtime engine supporting both PyTorch and ONNX Runtime. It automatically detects your hardware — CUDA on NVIDIA GPUs, Metal Performance Shaders on Apple Silicon, DirectML on Windows — and picks the fastest path.

Models move through three states:

Hot — loaded in memory, ready for instant inference
Warm — partially loaded, fast to activate
Cold — on disk, needs to be loaded before use

The agent manages these transitions automatically based on usage patterns and available memory.

Skill Execution

Skills are sandboxed extensions that give your agent new capabilities — think of them as tools. A skill might fetch your calendar, summarize a document, or query a database.

When the agent invokes a skill, it:

Spawns the skill as a child process
Sends a JSON request to the skill's stdin
Reads the JSON response from stdout
Enforces a timeout (30 seconds by default)
Caps output at 1MB to prevent runaway processes

The skill runs in a restricted environment — no inherited environment variables, limited filesystem access, bounded output. If it misbehaves, the agent terminates it cleanly (SIGTERM first, then SIGKILL after a grace period).

Skills can be written in any language. The agent doesn't care if it's Rust, Node.js, or Python — it only cares about the JSON protocol over stdin/stdout.

Assistants: Orchestration on Top

Assistants sit above skills and models. They combine a system prompt, tool bindings, safety guardrails, and workflow logic into a coherent persona.

An assistant might:

Use a summarization skill to condense a long email
Call a calendar skill to check your availability
Route through a local model for privacy-sensitive queries
Hand off to a human if it can't resolve something

Assistants use a finite state machine internally, so they can handle multi-step workflows, wait for user confirmation, recover from errors, and track progress — all without you writing orchestration code.

Security by Default

Every model file is verified with SHA-256 checksums before loading. The manifest records the expected hash at publish time, and the agent checks it at install, startup, and upgrade. If a file has been tampered with, it's rejected immediately.

Skills run in a sandbox with no access to your environment variables, secrets, or filesystem beyond what's explicitly declared. Secrets are stored in an encrypted vault on disk, never passed to child processes.

What's Next

In the next post, we'll walk through building your first skill — a simple tool that your agent can invoke, written in about 30 lines of code.

Build Your First Skill in 30 Lines

2025-05-12T00:00:00.000Z

A skill is the simplest way to extend your Life Savor agent. It's a program that reads a JSON request from stdin, does something useful, and writes a JSON response to stdout. That's it.

Let's build one.

What We're Building

A "word count" skill. You give it text, it tells you how many words are in it. Simple, but it demonstrates the full skill lifecycle — manifest, implementation, and installation.

The Manifest

Every skill needs a skill.json that tells the agent what it is and how to run it:

{
  "skill_id": "word-count",
  "name": "Word Count",
  "version": "1.0.0",
  "description": "Counts the number of words in a given text input",
  "execution_tier": 1,
  "entrypoint": {
    "type": "node",
    "command": "node",
    "args": ["index.js"]
  }
}

The key fields:

skill_id — unique identifier (lowercase, hyphens only)
execution_tier — resource limits (1 is the most restricted, 3 is the most permissive)
entrypoint — how the agent launches your skill. This one runs node index.js

The Implementation

Here's the complete skill in Node.js:

const readline = require('readline');

const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const request = JSON.parse(line);

  let result;

  if (request.operation === 'count') {
    const text = request.payload.text || '';
    const words = text.trim().split(/\s+/).filter(Boolean);
    result = {
      status: 'ok',
      result: { word_count: words.length }
    };
  } else {
    result = {
      status: 'failed',
      error: `Unknown operation: ${request.operation}`
    };
  }

  process.stdout.write(JSON.stringify(result) + '\n');
});

That's 20 lines of actual logic. The agent sends a JSON object with an operation and payload, and your skill responds with a status and result.

The Same Thing in Python

import json
import sys

for line in sys.stdin:
    request = json.loads(line.strip())

    if request["operation"] == "count":
        text = request.get("payload", {}).get("text", "")
        words = text.split()
        result = {"status": "ok", "result": {"word_count": len(words)}}
    else:
        result = {"status": "failed", "error": f"Unknown operation: {request['operation']}"}

    print(json.dumps(result), flush=True)

Same protocol, different language. The agent doesn't care — it just speaks JSON over stdio.

Install and Test

Put your skill.json and index.js (or skill.py) in a directory, then install it locally:

lsai-cli component install ./word-count

Check that it registered:

lsai-cli component list

Your agent can now invoke the word-count skill whenever it needs to count words in a document.

Adding Configuration

What if your skill needs an API key or user preferences? Add a config_schema to your manifest:

{
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "include_characters": {
        "type": "boolean",
        "title": "Include Character Count",
        "description": "Also return the character count alongside word count",
        "default": false
      }
    }
  }
}

The platform renders a setup wizard automatically from your schema — no custom UI needed. Users configure your skill through a clean, consistent interface across web, iOS, and desktop.

Adding Setup Steps

For skills that need credentials or multi-step configuration, define setup_steps:

{
  "setup_steps": [
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Configure how the word counter behaves",
      "fields": ["include_characters"]
    }
  ]
}

Each step groups related fields into a focused screen. You can add a validation_command to any step if you need server-side validation (like testing an API key before proceeding).

What Happens at Runtime

When the agent invokes your skill:

It spawns your process in a sandbox (cleared environment, restricted paths)
Writes the JSON request to your stdin
Waits up to 30 seconds for a response on stdout
Caps output at 1MB
Terminates the process if it exceeds limits

Your skill doesn't need to manage connections, authentication, or lifecycle — the agent handles all of that.

Next Steps

This was the simplest possible skill. From here you can:

Add multiple operations (your skill can handle many different tools)
Use the MCP protocol instead of raw JSON for richer tool definitions
Access system components (like the knowledge store) via the bridge
Publish to the marketplace for other users to install

In the next post, we'll look at the full SDK and how to build more complex components.

The Life Savor Developer SDK: What You Can Build

2025-05-10T00:00:00.000Z

The Life Savor platform is built on a component architecture. Everything — from the AI models to the tools your agent uses — is a pluggable component that you can build, publish, and share. Here's what the SDK gives you.

Four Component Types

Type	What it does	Language
Skill	A tool your agent can invoke (fetch data, transform text, call APIs)	Any — Rust, Node.js, Python
Assistant	An orchestration layer that combines skills with prompts and guardrails	Rust, Python
Model	An AI model provider (local inference or API gateway)	Rust
System	A privileged platform service (voice, TTS, storage, caching)	Rust

Most developers will start with skills. They're the simplest to build, work in any language, and cover the most common use cases.

The CLI

Everything starts with lsai-cli:

# Install (macOS)
curl -fsSL https://download.lifesavor.ai/lsai-cli/latest/homebrew/install.sh | bash

# First-time setup
lsai-cli setup

# Create a component
lsai-cli components create --name my-skill --type skill --language node

# Set metadata
lsai-cli components update <id> \
  --description "Does something useful" \
  --category Productivity \
  --tags automation,utility

# Connect your GitHub repo
lsai-cli components connect --component <id> --repo-url https://github.com/you/my-skill

# Submit for review
lsai-cli components submit <id>

# Build for all platforms
lsai-cli builds submit --component <id> --all-platforms

# Publish (after QA approval)
lsai-cli components publish --component <id> --version 1.0.0 --notes CHANGELOG.md

The full lifecycle: create → metadata → connect repo → submit → build → QA → publish.

Skills: Any Language, One Protocol

Skills communicate over JSON stdin/stdout. The agent spawns your skill as a child process, sends a request, and reads the response. You can write skills in whatever language you're comfortable with.

The manifest (skill.json) declares your skill's identity, entrypoint, configuration schema, and setup steps. The platform renders the configuration UI automatically — you never build a settings page.

{
  "skill_id": "my-skill",
  "name": "My Skill",
  "version": "1.0.0",
  "description": "A useful skill for Life Savor agents",
  "execution_tier": 1,
  "entrypoint": {
    "type": "python",
    "command": "python",
    "args": ["skill.py"]
  }
}

Skills run sandboxed: cleared environment, restricted filesystem, bounded output, enforced timeouts.

Assistants: Orchestration Without Code

Assistants combine multiple skills into a coherent workflow. You define:

System prompt — with `` template substitution
Tool bindings — map logical names to concrete skill IDs
Guardrails — safety rules evaluated before/after LLM calls (block, warn, or log)
Handoff rules — when to transfer to another assistant or a human
Context strategy — how to manage the conversation window (sliding, summarize, truncate)

let definition = AssistantDefinitionBuilder::new()
    .id("support-assistant")
    .display_name("Support Assistant")
    .system_prompt_template("You help users with  questions.")
    .variable("domain", "account management")
    .build()?;

Assistants run in two modes: Interactive (conversational, with user confirmation steps) or Programmatic (execute to completion without interaction).

Models: Four Provider Patterns

If you're building a model component, you implement the LlmProvider trait in Rust:

API Gateway — route through the Life Savor API (centralized billing, no user API keys needed)
Local — run on the user's hardware via PyTorch or ONNX Runtime
BYOK — user supplies their own vendor API key, calls the API directly

The agent handles model state management (hot/warm/cold), hardware detection, health monitoring, and routing — your component just implements inference.

Voice and text-to-speech aren't model components — they're system components that provide an input/output channel to the agent. Think of voice as a way to get to a model, not a model itself.

The JavaScript SDK

For skills that need configuration, the JS SDK (skill-config-sdk.js) provides helpers for defining schemas and handling validation:

const { createConfigSchema, createSetupStep, handleValidation } = require('./skill-config-sdk');

const schema = createConfigSchema({
  properties: {
    api_key: {
      type: 'string',
      title: 'API Key',
      description: 'Your service API key',
      'x-secret': true
    }
  },
  required: ['api_key']
});

Fields marked x-secret are stored in the agent's encrypted vault and masked in the UI. The platform handles all the crypto — you just declare which fields are sensitive.

The Marketplace

Once your component passes QA review, it's published to the marketplace. Users can discover and install it from the web, mobile app, or CLI:

lsai-cli component install my-skill

Components are code-signed, checksum-verified, and sandboxed at runtime. The platform handles distribution, updates, and compatibility checking.

Getting Started

Install the CLI: curl -fsSL https://download.lifesavor.ai/lsai-cli/latest/homebrew/install.sh | bash
Create a developer account at developer.lifesavor.ai
Run lsai-cli setup with your API key
Create your first component: lsai-cli components create --name my-skill --type skill --language node

The developer documentation has full API references, examples, and guides for each component type.

We're excited to see what you build.

Become a Life Savor Developer: Build Components, Earn Revenue

2025-05-08T00:00:00.000Z

The Life Savor marketplace isn't just a place to find tools — it's a platform where developers earn real money by building components that other users install. Whether you build a simple skill, a fine-tuned model, or a full assistant workflow, you set the price and keep the majority of the revenue.

Here's how it works and what you can build.

The Opportunity

Every Life Savor agent is extensible. Users install components to add capabilities — a skill that connects to their CRM, a model fine-tuned for medical terminology, an assistant that handles customer support workflows. The marketplace is where supply meets demand.

As a developer, you publish components and choose your pricing model:

Pricing Model	How it works	Best for
Free	No charge, maximizes installs	Building reputation, open-source tools, lead generation
One-time	User pays once to install	Utilities, simple skills, standalone tools
Subscription	Recurring monthly revenue	Premium assistants, maintained integrations, model access

You set the price. The platform handles billing, distribution, updates, and compatibility.

What You Can Build

Skills — The Fastest Path to Revenue

Skills are the simplest component type and the easiest to monetize. A skill is a tool your agent can invoke — it could be anything from a weather lookup to a complex data pipeline.

Why skills sell:

Users need integrations with specific services (Slack, Jira, Salesforce, HubSpot)
Niche tools that solve real problems command premium prices
Low maintenance once built — the sandbox handles security and isolation

Revenue potential: A well-built skill in a popular category (Productivity, Communication, Developer Tools) with subscription pricing can generate steady recurring revenue from a growing user base.

Categories in demand:

Productivity — task management, scheduling, workflow automation
Communication — messaging integrations, email tools, notification routing
Developer Tools — code analysis, CI/CD helpers, testing utilities
Data — retrieval, transformation, API connectors
Security — scanning, compliance checking, credential management

Models — High Value, Technical Depth

Model components provide AI inference capabilities. This is where the highest-value opportunities live, especially for developers with ML expertise.

What you can build:

Fine-tuned models — take an open-source base model and fine-tune it for a specific domain (legal, medical, financial, code generation for a specific framework)
Quantized models — optimize existing models for edge devices (4-bit, 8-bit quantization for laptops and phones)
Specialized models — NER, classification, sentiment analysis, or other task-specific models
API wrappers — connect new model providers to the platform (emerging LLM APIs, specialized inference services)

Why models command premium pricing:

Fine-tuning requires expertise and compute that most users don't have
Domain-specific models deliver measurably better results than general-purpose ones
Users will pay for models that run locally on their hardware (privacy, speed, no API costs)

Revenue potential: A fine-tuned model for a specific industry (e.g., a legal document analyzer or a medical coding assistant) can justify subscription pricing because it delivers ongoing value that improves with updates.

Assistants — Workflow Automation

Assistants combine skills, models, and orchestration logic into complete workflows. They're the most complex component type but also the most valuable to end users.

What you can build:

A customer support assistant that triages tickets, looks up account info, and drafts responses
A research assistant that searches multiple sources, summarizes findings, and formats reports
A coding assistant tuned for a specific framework or language with custom guardrails
A personal finance assistant that categorizes transactions and generates insights

Why assistants sell:

They solve complete problems, not just individual tasks
Users pay for the orchestration logic — the "how things work together" part
Guardrails and handoff rules make them safe for business use
They can be customized per-user through configuration schemas

Revenue potential: Assistants that automate real business workflows (support, sales, operations) justify the highest subscription prices because they replace hours of manual work.

Fine-Tuning Services

If you have ML expertise, you can build and sell fine-tuned model components:

Start with an open-source base model (LLaMA, Mistral, Phi, Qwen)
Fine-tune with LoRA/QLoRA on domain-specific data
Package as a model component with the proper manifest
Publish with subscription pricing for ongoing updates

The platform supports LoRA adapter loading, so you can ship lightweight adapters that users apply on top of base models they already have installed. This means smaller downloads and faster iteration.

Getting Started

1. Create Your Developer Account

Sign up at developer.lifesavor.ai. You'll get access to the developer portal, API keys, and the component management dashboard.

2. Install the CLI

curl -fsSL https://download.lifesavor.ai/lsai-cli/latest/homebrew/install.sh | bash
lsai-cli setup

3. Build Your First Component

Start with a skill — it's the fastest path from idea to published component:

lsai-cli components create --name my-skill --type skill --language node

4. Set Your Pricing

Choose free, one-time, or subscription. You can always change this later, but starting with a free tier to build installs and reviews is a common strategy.

5. Submit and Publish

lsai-cli components submit <id>
lsai-cli builds submit --component <id> --all-platforms
# After QA approval:
lsai-cli components publish --component <id> --version 1.0.0 --notes CHANGELOG.md

Tips for Success

Start small. Your first component doesn't need to be complex. A well-built skill that solves one problem cleanly will outperform a bloated one that tries to do everything.

Pick a niche. The marketplace rewards specificity. "Salesforce Lead Scorer" will outsell "Generic CRM Tool" because users search for solutions to specific problems.

Maintain your components. Subscription pricing works when users trust that you'll keep things updated. Regular updates, responsive support, and clear changelogs build that trust.

Use the configuration system. Skills with proper config_schema and setup_steps get higher ratings because they're easier to set up. The platform renders the UI for you — just declare your fields.

Write documentation. Components with a usage_guide and examples in their manifest get more installs. The agent's LLM can read your docs to help users get started.

The Developer Community

We're building a platform where independent developers can earn meaningful revenue by solving real problems. The marketplace is young — early developers who establish themselves in key categories will have a significant advantage as the user base grows.

Join us at developer.lifesavor.ai and start building.

Privacy First: How the PII Interceptor Protects Your Data

2025-05-06T00:00:00.000Z

Every message that flows through your Life Savor agent — whether it's going to an AI model, a skill, another agent, or a system event — passes through the PII Interceptor first. It's not optional. It's not configurable by components. It's a fixed part of the pipeline that protects your personal information before anything else touches it.

Here's how it works and why we built it this way.

The Problem

When you talk to an AI agent, you inevitably share personal information. Your name, email, phone number, address, dates of birth — it all comes up naturally in conversation. If that data gets sent to a cloud model, stored in a skill's database, or relayed to another agent, you've lost control of it.

Most platforms treat privacy as an afterthought — a settings toggle or a terms-of-service checkbox. We treat it as architecture.

How the Interceptor Works

The interceptor sits in a fixed position in the message pipeline. Components cannot bypass it, reorder it, or disable it. Every message goes through two detection layers:

Layer 1: Pattern Matching

A regex scanner catches structured PII with known formats:

Credit card numbers
Social Security numbers
Email addresses
Phone numbers
Dates of birth

This is fast and deterministic — no AI model needed.

Layer 2: AI-Powered Detection

A Named Entity Recognition (NER) model runs locally on your device to catch PII that doesn't follow a fixed pattern:

Names (given names, surnames)
Addresses (cities, streets, building numbers)
Identity documents (driver's license numbers, passport numbers)
Temporal information (dates, times that could identify you)

The NER model supports multiple languages and runs entirely on your hardware. Your text never leaves your device for PII detection.

What Happens When PII Is Found

When the interceptor detects personal information, it doesn't just delete it. It replaces it with a vault tag — a structured token that preserves the semantic meaning without exposing the actual data:

"My email is john@example.com" 
    → "My email is <<PII:EMAIL:agent1,user1,org1,a3f2c1>>"

The vault tag tells the AI model "there's an email address here" without revealing what it is. The model can still reason about the message ("the user shared their email") without ever seeing the actual address.

The original value is stored in your local encrypted vault, tied to your identity. Only you can retrieve it.

Security Levels

Not all PII is equally sensitive. A first name is less sensitive than a Social Security number. The interceptor classifies detected PII into security levels:

Level	Label	Examples
0	Open	No PII detected
1	Personal	Names, cities
2	Private	Email addresses, phone numbers
3	Protected	Dates of birth, ages
4	Guarded	Driver's license numbers
5	Critical	SSNs, passport numbers, credit cards
6	Compound	Multiple high-sensitivity items together

These levels control who can de-tokenize (retrieve the original value). Low-sensitivity items can be resolved automatically when you request them. High-sensitivity items require explicit confirmation. Critical items may be permanently tokenized depending on your settings.

Exfiltration Detection

The interceptor doesn't just look at individual messages — it watches patterns across conversations. If a skill or model starts accumulating multiple types of PII from you (your name in one message, your address in another, your phone number in a third), the interceptor flags it as a potential exfiltration attempt and blocks further data flow.

This catches sophisticated attacks where individually harmless requests combine to build a profile of you.

Every Channel, Every Direction

The interceptor covers all communication paths:

LLM inference — before your message reaches any model
Skill I/O — before data is sent to any skill process
Agent-to-agent — before messages relay between agents
System events — before internal events are logged or transmitted

And it works in both directions:

Inbound: PII is tokenized before reaching the model, then content safety is checked
Outbound: Content safety is checked first, then PII verification ensures no new personal data was introduced

Per-Component Configuration

You can configure interception levels per provider or skill:

Full (default) — regex + NER scanning on everything
Regex only — fast pattern matching without the NER model
Disabled — for trusted system components that need raw data (like your local calendar integration)

You can also allowlist specific PII categories per component. If your email skill legitimately needs to see email addresses, you can grant that — but only for that specific skill.

De-tokenization: Getting Your Data Back

When you need the original value (for example, to actually send that email), you request de-tokenization. The system checks:

Are you the owner of this data?
Does the requesting component have permission?
What's the de-tokenization policy for this PII category?

Every de-tokenization is logged in an audit trail. You can see exactly who accessed what, when, and why.

Why This Matters

Most AI platforms send your data to the cloud, process it on someone else's servers, and store it in someone else's database. Even "private" modes often just mean "we won't use it for training" — your data still leaves your device.

With Life Savor:

PII detection runs locally on your hardware
Sensitive data is replaced before it reaches any model or skill
Original values are stored in your local encrypted vault
De-tokenization requires your explicit permission
Every access is audited

Your data stays yours. That's not a feature — it's the architecture.

The Developer MCP Server: AI-Powered Development From Your IDE

2025-05-04T00:00:00.000Z

Building components for Life Savor means working with manifests, build pipelines, bridge protocols, and platform APIs. The Developer MCP Server puts all of that directly in your IDE — no context switching, no browser tabs, no copy-pasting between docs and code.

What Is It?

The Developer MCP Server is a hosted service that implements the Model Context Protocol. You connect to it from any MCP-compatible IDE (VS Code, Cursor, Windsurf, Claude Desktop) and get access to 40+ tools for building, debugging, and managing your components — all without leaving your editor.

It's like having a platform expert sitting next to you who can scaffold projects, validate your manifests, check build status, search documentation, and explain how things work.

Setting It Up

Add this to your IDE's MCP configuration:

{
  "mcpServers": {
    "lifesavor-developer": {
      "url": "https://mcp.developer.lifesavor.ai/sse",
      "headers": {
        "Authorization": "Bearer lsk_your_api_key_here"
      }
    }
  }
}

That's it. Your IDE connects, authenticates with your API key, and you have access to the full toolset.

What You Can Do

Scaffold Components Instantly

Instead of reading docs and creating files manually:

"Scaffold a new Python skill called weather-lookup"

The server generates the complete project structure — manifest, entrypoint, configuration schema, build config — ready to customize.

Validate Before You Submit

Catch manifest errors before they hit the build pipeline:

"Validate my manifest"

The server checks your TOML for syntax errors, missing fields, invalid values, and returns actionable fixes. It can even auto-fix common issues.

Debug Bridge Protocol Issues

When your skill isn't communicating correctly with system components:

"Diagnose bridge error COMPONENT_TIMEOUT"

You get a structured diagnosis: what the error means, common causes, diagnostic steps, and links to relevant documentation.

"Explain the bridge flow for a skill calling the summarize operation"

Step-by-step breakdown of the dispatch flow, including timeouts and possible error codes at each stage.

Check Build Status Without Leaving Your Editor

"Show me my recent builds"

"Get the logs for my latest failed build"

No more switching to the portal to check if your build passed. The server pulls live data from the platform.

Search Documentation Semantically

"How do I handle validation commands in a setup step?"

The server uses semantic search over the full SDK documentation. It doesn't just keyword-match — it understands what you're asking and returns the most relevant sections.

AI-Powered Explanations

"Explain how the bridge dispatch works"

"What's the component lifecycle?"

The server uses retrieval-augmented generation (RAG) to give you accurate, documentation-grounded explanations. It pulls relevant docs, then generates a clear answer — no hallucination, no outdated information.

Generate Code

"Generate a bridge request handler for the summarize and translate operations"

"Generate test stubs for my skill's validate_credentials operation"

The server produces handler skeletons and test stubs tailored to your component type and language, following platform conventions.

Manage Components

"Create a new skill component called data-enricher"

"Update my component's description and tags"

"Submit my component for review"

"Connect my GitHub repo"

Full component lifecycle management without touching the CLI or portal.

How It Speeds Up Development

Before the MCP server:

Open browser → navigate to docs → search for the right page
Read the docs → switch back to IDE → write code
Open terminal → run CLI commands → check output
Open portal → check build status → read logs
Back to IDE → fix the issue → repeat

With the MCP server:

Ask your IDE → get the answer → write code → validate → submit

Everything happens in one place. Your AI assistant has full context about the platform, your components, your builds, and the documentation. It can answer questions, generate code, and take actions — all in the flow of your work.

What's Under the Hood

The MCP server is a hosted Node.js service that:

Authenticates via your existing API key (lsk_ prefix) or OAuth
Delegates data operations to the Developer API (single source of truth)
Uses Amazon Bedrock + Knowledge Bases for semantic search and AI features
Maintains session state (active component, language preference) in Redis
Scales horizontally behind an ALB with sticky sessions for SSE

Your data is isolated — you can only access your own components, builds, and logs. The server enforces ownership checks on every request.

Getting Started

Generate an API key at developer.lifesavor.ai/api-keys
Add the MCP server config to your IDE
Start asking questions

The server works with any MCP-compatible client. If your IDE supports MCP, it supports the Life Savor Developer Server.

Try it: ask it to scaffold your first component, then validate the manifest, then explain how to add a configuration schema. The whole flow happens in your editor.

Preparing Your Developer Environment: Account, CLI, GitHub App, and First Build

2025-05-02T00:00:00.000Z

Before you build your first component, you need a few things set up: a developer account, the CLI tool, a connected GitHub repository, and the GitHub App installed. This guide walks through the complete setup so you're ready to build, submit, and publish.

Step 1: Create Your Developer Account

Head to developer.lifesavor.ai and sign up. You can use Google OAuth or email — either works. Complete the developer agreement and fill in your profile.

Once you're in, generate an API key from the portal (Settings → API Keys). Your key will have an lsk_ prefix. Save it somewhere secure — you'll need it for the CLI and the MCP server.

API keys have scopes:

Read — view components, builds, logs
Write — create, update, submit, build, publish
For development, generate a key with both scopes

Step 2: Install the CLI

The lsai-cli is your primary tool for managing components from the terminal.

# macOS (Homebrew)
curl -fsSL https://download.lifesavor.ai/lsai-cli/latest/homebrew/install.sh | bash

# Debian / Ubuntu
curl -fsSL https://download.lifesavor.ai/lsai-cli/apt/setup.sh | sudo bash

# Fedora / RHEL / Amazon Linux
curl -fsSL https://download.lifesavor.ai/lsai-cli/yum/setup.sh | sudo bash

# Windows
winget install LifeSavorAI.lsai-cli

# From source (Rust 1.75+)
cargo install --path developer/cli

Then configure it with your API key:

lsai-cli setup
# Paste your lsk_ key when prompted

# Verify it worked
lsai-cli whoami

You should see your display name, email, and key scopes.

Step 3: Install the GitHub App

The Life Savor GitHub App gives the build pipeline access to your repository. It replaces the old shared-token approach with scoped, per-developer access that you control.

Why a GitHub App?

You grant access only to the repos you choose
Permissions are scoped (read-only code access for builds)
You can revoke access anytime from your GitHub settings
No shared tokens or manual key exchange

How to install:

Go to your component's page in the developer portal
Click "Connect Repository"
You'll be redirected to GitHub to install the Life Savor app
Select the repository (or repositories) you want to grant access to
GitHub redirects you back — the connection completes automatically

Or from the CLI:

lsai-cli components connect \
  --component <component-id> \
  --repo-url https://github.com/you/my-skill

If the GitHub App isn't installed yet, the CLI will print the installation URL and guide you through it.

Already installed the app? If you've previously installed it for another component, the platform detects your existing installation and skips the install step — it just connects the new repo directly.

Step 4: Create Your First Component

lsai-cli components create \
  --name my-first-skill \
  --type skill \
  --language node

This creates a draft component on the platform and returns a component ID. Write it down.

Step 5: Set Required Metadata

Before you can submit for review, you need a description, category, tags, compatibility, and license:

lsai-cli components update <component-id> \
  --description "A skill that does something useful" \
  --category Productivity \
  --tags automation,utility \
  --compatibility linux,macos,windows \
  --license MIT

Valid categories: Productivity, Communication, Developer Tools, Data, Media, Security, Automation, Monitoring, General

Valid platforms: linux, macos, windows, ios, android, tvos

Valid licenses: MIT, Apache-2.0, GPL-3.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL-3.0, Proprietary, Custom

Step 6: Add Build Configuration

Create a lifesavor-build.yml in your repository root:

version: 1
component:
  type: skill
  name: my-first-skill
build:
  language: node
  command: npm run build
  artifact: dist/

For Rust components:

version: 1
component:
  type: skill
  name: my-first-skill
build:
  language: rust
  command: cargo build --release
  artifact: target/release/my-first-skill

This tells the build pipeline how to compile your component and where to find the output.

Step 7: Set Build Targets

Choose which platforms to build for:

lsai-cli builds set-targets --component <component-id> \
  --platforms linux-x86_64,linux-arm64,macos-arm64,windows-x86_64

You can start with just one platform and add more later.

Step 8: Submit for Review

lsai-cli components submit <component-id>

This puts your component in the QA review queue. The platform checks that all required metadata is present. If anything's missing, you'll get a clear error message telling you what to fix.

Step 9: Trigger a Build

# Build for all configured platforms
lsai-cli builds submit --component <component-id> --all-platforms

# Or just one platform
lsai-cli builds submit --component <component-id> --platform linux-x86_64

Check build status:

lsai-cli builds list --component <component-id>
lsai-cli builds logs --component <component-id> --status failed

Step 10: Publish

Once QA approves your component and you have at least one successful build:

lsai-cli components publish \
  --component <component-id> \
  --version 1.0.0 \
  --notes "Initial release"

Your component is now live on the marketplace.

Optional: Set Up the MCP Server

For a faster development experience, connect the Developer MCP Server to your IDE. Add this to your MCP configuration:

{
  "mcpServers": {
    "lifesavor-developer": {
      "url": "https://mcp.developer.lifesavor.ai/sse",
      "headers": {
        "Authorization": "Bearer lsk_your_key_here"
      }
    }
  }
}

Now you can scaffold, validate, build, and manage components directly from your editor.

Optional: Set Up Webhooks

Get notified when builds complete or reviews finish:

lsai-cli webhooks create \
  --component <component-id> \
  --url https://your-server.com/webhooks/lifesavor \
  --events build.succeeded,build.failed,review.approved

Webhook payloads are signed with HMAC-SHA256 so you can verify they're authentic.

Optional: Build Secrets

If your build needs API keys or credentials (for integration tests, for example):

lsai-cli secrets set --component <component-id> --key MY_API_KEY --value sk-abc123

Secrets are stored encrypted and injected as environment variables during builds. They're never exposed in logs.

The Complete Flow

Account → CLI → GitHub App → Create → Metadata → Build Config → Submit → Build → Publish

Once this is set up, your ongoing workflow is just: push code → build triggers → publish new version. The infrastructure stays out of your way.

Troubleshooting

"Repository access denied" — The GitHub App isn't installed or doesn't have access to that repo. Visit the installation URL and grant access.

"Missing required fields" — Run lsai-cli components status <id> to see what's missing before submission.

"Build failed" — Check logs with lsai-cli builds logs --component <id> --status failed. Common issues: missing dependencies, wrong artifact path, build command errors.

"Key expired" — Generate a new API key from the portal and run lsai-cli setup again.

That's everything. You're set up to build, test, and publish components on the Life Savor platform. Start with a simple skill, get comfortable with the workflow, then scale up to models and assistants.

What Happens When You Talk to Your Agent

2025-04-30T00:00:00.000Z

You type a message. A few seconds later, your agent responds. But what actually happens in between? Here's the full lifecycle of a request through the Life Savor agent.

The Journey of a Message

You type "Summarize my last 5 emails"
    ↓
1. PII Interceptor scans your message
2. Content Safety checks the sanitized text
3. Inference Bridge routes to your configured model
4. Model generates a plan: "I need to call the email skill"
5. Agent invokes the email skill (sandboxed)
6. Skill returns your 5 most recent emails
7. PII Interceptor scans the skill output
8. Model receives sanitized emails, generates summary
9. Content Safety checks the response
10. PII Interceptor verifies no new PII leaked
11. Response delivered to you

Step by Step

1. Interception (Inbound)

Your message hits the interceptor pipeline before anything else sees it. The regex scanner checks for structured PII (emails, phone numbers, credit cards). The NER model checks for unstructured PII (names, addresses). Anything sensitive gets replaced with vault tags.

The model never sees your actual email address — it sees <<PII:EMAIL:...>> and knows "there's an email here" without knowing what it is.

2. Model Routing

The Inference Bridge looks at what models you have installed and healthy. If you have a local LLaMA loaded (hot state), it routes there. If you're using GPT-4o via API, it goes through the gateway. The routing is automatic based on your configuration and model availability.

3. Tool Use

The model decides it needs to call a skill. It generates a tool call request — "invoke the email skill with operation list_recent and parameter count: 5."

The agent validates this against the skill's permission graph. Does this model have permission to invoke this skill? Is the skill healthy? Is it within rate limits?

4. Skill Execution

The agent spawns the email skill as a sandboxed child process. It sends the request via JSON stdin. The skill fetches your emails (using credentials from the encrypted vault), formats the response, and writes it to stdout.

The skill's output goes through the interceptor too — any PII in the email content gets tokenized before the model sees it.

5. Response Generation

The model receives the sanitized email summaries and generates your response. This output goes through content safety (checking for harmful content) and then PII verification (ensuring the model didn't hallucinate or reconstruct personal information).

6. Delivery

The clean, safe response reaches you. The whole thing took a few seconds, but your personal information never left your device unprotected, and every step was logged for your audit trail.

Why This Order Matters

The interception order is fixed and enforced at the pipeline level. Components cannot bypass it, reorder it, or disable it. This means:

No skill can see your raw PII unless explicitly allowlisted
No model receives unscanned input
No response leaves without safety verification
Every step is traceable via correlation IDs

This isn't a feature you enable — it's how the system works by default.

Local vs Cloud Models: When to Use Each

2025-04-28T00:00:00.000Z

Life Savor supports both local models (running on your hardware) and cloud models (via API). You're not locked into either — you can mix and match based on what you're doing. Here's how to think about the tradeoff.

When Local Makes Sense

Privacy-sensitive work. If you're processing medical records, legal documents, financial data, or anything you wouldn't want leaving your device — local models keep everything on your hardware. The PII interceptor adds another layer, but local inference means the data never hits a network at all.

Offline use. On a plane, in a tunnel, or somewhere with unreliable internet — local models work regardless. No API calls, no latency spikes, no timeouts.

Predictable latency. Local inference has consistent response times. No cold starts, no rate limits, no queue behind other users. Once a model is in hot state, responses are immediate.

Cost at scale. If you're making hundreds of requests per day, local inference is effectively free after the initial model download. No per-token billing.

When Cloud Makes Sense

Capability. The largest, most capable models (GPT-4o, Claude 3.7 Sonnet, Gemini 1.5 Pro) require more compute than most personal devices can provide. If you need frontier-level reasoning, cloud APIs deliver it.

Hardware constraints. Running a 70B parameter model requires significant GPU memory. If you're on a laptop without a dedicated GPU, smaller local models may not match the quality you need. Cloud models have no hardware requirements on your end.

Convenience. Cloud models are instant — no download, no setup, no disk space. Install the component and start using it.

The Hybrid Approach

Most users end up with a mix:

A local model for everyday tasks (quick questions, drafting, summarization)
A cloud model for complex reasoning (analysis, coding, research)
The agent routes automatically based on what's available and healthy

You can configure routing preferences — "prefer local when available, fall back to cloud" — or let the agent decide based on the task.

Hardware Guidelines for Local Models

Model Size	RAM Needed	Good For
1-3B (TinyLlama, Phi-3 Mini)	4-6 GB	Simple tasks, edge devices
7-8B (Mistral 7B, LLaMA 3 8B)	8-12 GB	General use, good quality
13-22B (CodeStral, DeepSeek Coder)	16-24 GB	Specialized tasks, coding
70B+ (LLaMA 3 70B)	48+ GB	Near-frontier quality, requires GPU

Quantized models (4-bit) cut memory requirements roughly in half with minimal quality loss. The marketplace has pre-quantized versions of popular models.

BYOK: A Middle Ground

If you want cloud model quality but don't want billing through the platform, BYOK (Bring Your Own Key) components let you use your own API key directly. Your requests go straight to the vendor — no platform middleman, no markup. You just pay the vendor directly.

Bottom Line

There's no wrong answer. Start with what's convenient, then optimize based on your actual usage patterns. The agent makes switching easy — install a new model component, and it's available immediately.

Your Data Never Leaves Your Device (Unless You Want It To)

2025-04-26T00:00:00.000Z

Most AI platforms work like this: you type something, it goes to a server, gets processed, and comes back. Your data lives on someone else's infrastructure, governed by someone else's privacy policy.

Life Savor works differently.

What Stays Local

Your conversations — stored in an encrypted database on your device
Your credentials — API keys, tokens, and passwords in a local encrypted vault
Your PII — detected and tokenized before it reaches any model or skill
Your model inference — when using local models, computation happens entirely on your hardware
Your skill data — skills run in a sandbox on your device

What Goes to the Cloud (Only When You Choose)

Cloud model requests — if you use GPT-4o, Claude, or other API models, your (PII-sanitized) message goes to that provider
Platform sync — agent status, installed components, and configuration sync with the platform for multi-device support
Marketplace installs — downloading components requires internet

Even when data does leave your device, the PII interceptor has already replaced sensitive information with vault tags. The cloud model sees <<PII:EMAIL:...>> — not your actual email address.

How We Enforce This

This isn't a promise in a terms-of-service document. It's enforced by architecture:

The interceptor is mandatory. Every message passes through PII scanning before reaching any model or skill. Components cannot bypass it.
Skills are sandboxed. They run with a cleared environment — no access to your filesystem, environment variables, or network unless explicitly declared and approved.
Secrets never leave the vault. API keys and credentials are resolved at runtime by the agent. Skills receive the service response, not the key itself.
Local models are truly local. PyTorch and ONNX Runtime execute on your CPU/GPU. No telemetry, no phone-home, no cloud dependency.
Everything is auditable. Every PII detection, every de-tokenization, every skill invocation is logged locally. You can inspect exactly what happened.

You're in Control

Want to disable PII scanning for a trusted skill? You can. Want to allow a specific model to see your email address? Configure it. Want to run completely offline with no cloud models? Install local models and disconnect.

The defaults are private. The overrides are yours.

Anatomy of a Skill Manifest: Every Field Explained

2025-04-24T00:00:00.000Z

Every skill has a skill.json manifest that tells the agent what it is, how to run it, what it needs, and how users configure it. Here's every field, explained.

Required Fields

{
  "skill_id": "weather-lookup",
  "name": "Weather Lookup",
  "version": "1.0.0",
  "description": "Fetches current weather and forecasts for any location",
  "execution_tier": 1
}

Field	Rules	Purpose
`skill_id`	Lowercase alphanumeric + hyphens only	Unique identifier on the marketplace
`name`	Any string	Human-readable display name
`version`	Semver (e.g. `1.2.0`)	Used for updates and compatibility
`description`	Minimum 10 characters	Shown in marketplace search results
`execution_tier`	1, 2, or 3	Controls resource limits and sandbox privileges

Execution Tiers

Tier 1 — most restricted. Short timeouts, minimal filesystem access. Good for simple tools.
Tier 2 — moderate. Longer timeouts, more memory. Good for API integrations.
Tier 3 — least restricted. Extended timeouts, broader access. For complex processing.

Entrypoint

Tells the agent how to launch your skill:

{
  "entrypoint": {
    "type": "node",
    "command": "node",
    "args": ["dist/index.js"],
    "env": {
      "NODE_ENV": "production"
    }
  }
}

Field	Options	Notes
`type`	`node`, `python`, `binary`, `wasm`	Determines how the agent spawns the process
`command`	Any executable	For `binary`, relative to skill directory. For `node`/`python`, the system command.
`args`	Array of strings	Arguments passed to the command
`env`	Key-value map	Environment variables set for the process (in addition to sandbox defaults)

The agent clears the environment before launching your skill. Only PATH and your declared env vars are available. This prevents accidental secret leakage.

Configuration Schema

Defines what settings your skill accepts from users:

{
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "Your weather service API key",
        "x-secret": true
      },
      "units": {
        "type": "string",
        "title": "Temperature Units",
        "description": "Celsius or Fahrenheit",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      },
      "cache_ttl": {
        "type": "integer",
        "title": "Cache Duration",
        "description": "How long to cache results (seconds)",
        "default": 300
      }
    },
    "required": ["api_key"]
  }
}

Supported Field Types

Type	UI Control	Example
`string`	Text input (password if `x-secret`)	API keys, URLs, names
`number`	Number input (decimals)	Thresholds, ratios
`integer`	Number input (whole numbers)	Counts, timeouts
`boolean`	Toggle switch	Feature flags
`array`	Tag input / multi-select	Lists of values

The `x-secret` Flag

Fields marked "x-secret": true are:

Stored in the agent's encrypted vault (not in plaintext config)
Masked in the UI (shown as ••••••••)
Never logged or exposed in error messages
Resolved at runtime and passed to your skill securely

Setup Steps

Groups config fields into a guided wizard:

{
  "setup_steps": [
    {
      "step_id": "credentials",
      "title": "API Credentials",
      "description": "Connect your weather service account",
      "fields": ["api_key"],
      "validation_command": "validate_credentials"
    },
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Configure display and caching options",
      "fields": ["units", "cache_ttl"]
    }
  ]
}

Field	Required	Purpose
`step_id`	Yes	Unique identifier for the step
`title`	Yes (3-100 chars)	Displayed as the step heading
`description`	Yes (10-500 chars)	Help text below the heading
`fields`	Yes	Config field names from `config_schema` that belong to this step
`validation_command`	No	Skill operation name the agent invokes to validate before advancing

When validation_command is set, the agent calls your skill with that operation and the user's field values. Your skill can test the API key, verify a connection, or check permissions — and return success or a specific error message.

Pass-Through Config

When the agent invokes your skill, the user's configured values are available to your process. The config is persisted locally on the agent and merged with any platform-provided overrides at install time.

Here's how it flows:

User fills in the setup wizard (or the platform sends config during install)
Values are stored locally — secrets go to the encrypted vault, plain values to config.json
At invocation time, the agent resolves secrets from the vault and passes the full config to your skill as part of the invocation payload

Your skill receives the config in the request context:

{
  "operation": "get_weather",
  "payload": { "location": "Seattle" },
  "config": {
    "api_key": "resolved-from-vault",
    "units": "celsius",
    "cache_ttl": 300
  }
}

You never need to manage credential storage yourself. Declare x-secret, and the platform handles encryption, vault storage, and runtime resolution.

Capabilities

Optional flags for special skill behaviors:

{
  "capabilities": {
    "rag_provider": true
  }
}

Flag	Purpose
`rag_provider`	This skill provides retrieval-augmented generation content to the knowledge store

Dependencies

Declare other skills your skill requires:

{
  "dependencies": [
    {
      "skill_id": "auth-helper",
      "min_version": "2.0.0"
    }
  ]
}

The agent checks dependencies at install time and warns the user if required skills are missing or unhealthy.

Documentation

Bundle docs with your skill for both users and the agent's LLM:

{
  "documentation": {
    "usage_guide": "docs/usage.md",
    "examples": [
      { "title": "Basic Weather Query", "file": "docs/examples/basic.md" },
      { "title": "Forecast Integration", "file": "docs/examples/forecast.md" }
    ]
  }
}

The agent's LLM can read your documentation to help users get started. Good docs = better user experience = more installs.

Complete Example

{
  "skill_id": "weather-lookup",
  "name": "Weather Lookup",
  "version": "1.0.0",
  "description": "Fetches current weather and forecasts for any location worldwide",
  "author": "Your Name",
  "license": "MIT",
  "tags": ["weather", "forecast", "location"],
  "execution_tier": 1,
  "entrypoint": {
    "type": "node",
    "command": "node",
    "args": ["dist/index.js"]
  },
  "capabilities": {},
  "dependencies": [],
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "Your weather service API key",
        "x-secret": true
      },
      "units": {
        "type": "string",
        "title": "Units",
        "description": "Temperature units",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["api_key"]
  },
  "setup_steps": [
    {
      "step_id": "credentials",
      "title": "API Credentials",
      "description": "Enter your weather service API key",
      "fields": ["api_key"],
      "validation_command": "validate_credentials"
    },
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Choose your display preferences",
      "fields": ["units"]
    }
  ],
  "documentation": {
    "usage_guide": "docs/usage.md"
  }
}

Bookmark this page. You'll reference it every time you build a new skill.

Adding a Setup Wizard to Your Skill

2025-04-22T00:00:00.000Z

A skill with a setup wizard gets more installs. Users see a clean, guided configuration flow instead of guessing what values to enter. The platform renders the UI automatically from your manifest — you just declare the fields and steps.

The Basics

You need two things in your skill.json:

A config_schema defining what fields exist
A setup_steps array grouping those fields into screens

{
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "Your service API key (find it in Settings → API)",
        "x-secret": true
      },
      "workspace_id": {
        "type": "string",
        "title": "Workspace ID",
        "description": "The workspace to connect to"
      },
      "notify_on_error": {
        "type": "boolean",
        "title": "Error Notifications",
        "description": "Send a notification when the skill encounters an error",
        "default": true
      }
    },
    "required": ["api_key", "workspace_id"]
  },
  "setup_steps": [
    {
      "step_id": "credentials",
      "title": "Connect Your Account",
      "description": "Enter your API key and workspace ID to get started",
      "fields": ["api_key", "workspace_id"],
      "validation_command": "validate_credentials"
    },
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Configure how the skill behaves",
      "fields": ["notify_on_error"]
    }
  ]
}

The platform renders step 1 first. The user fills in their API key and workspace ID, clicks Next, and the agent validates their credentials before advancing to step 2.

Adding Server-Side Validation

The validation_command field tells the agent to invoke your skill with that operation name before advancing to the next step. This lets you verify credentials, test connections, or check permissions in real time.

Here's a validation handler in Node.js:

const readline = require('readline');
const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const request = JSON.parse(line);

  if (request.operation === 'validate_credentials') {
    const { api_key, workspace_id } = request.payload;

    // Test the credentials against the external service
    fetch(`https://api.example.com/workspaces/${workspace_id}`, {
      headers: { 'Authorization': `Bearer ${api_key}` }
    })
    .then(res => {
      if (res.ok) {
        process.stdout.write(JSON.stringify({
          status: 'ok',
          result: { message: 'Connected successfully' }
        }) + '\n');
      } else if (res.status === 401) {
        process.stdout.write(JSON.stringify({
          status: 'failed',
          error: 'Invalid API key. Check that your key has workspace access.'
        }) + '\n');
      } else if (res.status === 404) {
        process.stdout.write(JSON.stringify({
          status: 'failed',
          error: 'Workspace not found. Double-check the workspace ID.'
        }) + '\n');
      }
    })
    .catch(err => {
      process.stdout.write(JSON.stringify({
        status: 'failed',
        error: `Connection failed: ${err.message}`
      }) + '\n');
    });
  }
});

The user sees your error message directly in the wizard. Clear, specific error messages ("Invalid API key" vs "Something went wrong") make the difference between a 5-star review and a support ticket.

Field Types in Practice

Secrets (API keys, tokens)

{
  "api_key": {
    "type": "string",
    "title": "API Key",
    "description": "Your service API key",
    "x-secret": true
  }
}

Rendered as a password field. Stored in the encrypted vault. Never shown in logs.

Dropdowns (enum values)

{
  "region": {
    "type": "string",
    "title": "Region",
    "description": "Which data center to connect to",
    "enum": ["us-east", "us-west", "eu-west", "ap-southeast"],
    "default": "us-east"
  }
}

Rendered as a dropdown select. The default pre-selects a value.

Toggles (booleans)

{
  "auto_sync": {
    "type": "boolean",
    "title": "Auto-Sync",
    "description": "Automatically sync data every hour",
    "default": true
  }
}

Rendered as a toggle switch.

Numbers

{
  "max_results": {
    "type": "integer",
    "title": "Max Results",
    "description": "Maximum number of results to return per query",
    "default": 10
  }
}

Rendered as a number input.

Lists (arrays)

{
  "channels": {
    "type": "array",
    "title": "Channels",
    "description": "Slack channels to monitor",
    "items": { "type": "string" },
    "default": ["general"]
  }
}

Rendered as a tag input where users can add/remove values.

Tips for Good Setup Wizards

Keep step 1 minimal. Just credentials. Users want to verify the connection works before configuring preferences.

Write helpful descriptions. Tell users where to find their API key. Link to the service's settings page in the description text.

Use defaults generously. Every field with a sensible default is one less decision for the user.

Validate early. If an API key is wrong, catch it in step 1 — don't let users configure 5 more screens before discovering the connection doesn't work.

Group logically. Credentials in one step, behavior in another, notifications in a third. Don't mix concerns.

Testing Your Wizard

Use the CLI to preview and test:

# Preview how the wizard will render
lsai-cli skill config preview

# Validate your schema
lsai-cli skill config validate

# Test a validation command with sample values
lsai-cli skill config test-validation \
  --step credentials \
  --values '{"api_key": "sk-test", "workspace_id": "ws-123"}'

This runs your validation handler locally so you can verify error messages and success responses before publishing.

Testing Your Component Locally Before Submitting

2025-04-20T00:00:00.000Z

Don't wait for the build pipeline to tell you something's broken. Test locally first — validate your manifest, run your skill in the sandbox, and catch issues before they cost you a build cycle.

Validate Your Manifest

lsai-cli skill config validate

This checks your skill.json for:

Missing required fields
Invalid field types
Schema syntax errors
Setup step references to non-existent fields
Version format issues

Fix everything this reports before submitting.

Install Locally

lsai-cli component install ./my-skill

This installs your skill into the local agent's skill directory, exactly as the marketplace would. The agent picks it up, registers it, and you can invoke it immediately.

Check it registered:

lsai-cli component list

Test Your Skill Manually

Send a request to your skill directly:

echo '{"operation":"my_operation","payload":{"key":"value"}}' | node dist/index.js

You should get a JSON response on stdout. If you get nothing, check:

Is your skill reading from stdin?
Is it writing to stdout (not stderr)?
Is the output valid JSON?
Does it include a status field?

Test Validation Commands

If your skill has setup steps with validation_command:

lsai-cli skill config test-validation \
  --step credentials \
  --values '{"api_key": "test-key-123"}'

This invokes your skill with the validation operation and shows you exactly what the user would see — success message or error.

Run in the Sandbox

The SDK includes a sandbox runner that applies the same restrictions the agent uses:

cargo run --bin sandbox-runner -- --manifest path/to/manifest.toml

This spawns your skill with:

Cleared environment (only PATH + declared env vars)
Restricted filesystem access
Output size limits
Timeout enforcement

If your skill works outside the sandbox but fails inside it, you're probably:

Reading environment variables that aren't declared
Accessing filesystem paths that aren't allowed
Producing output larger than 1MB
Taking longer than 30 seconds

Validate Build Config

lsai-cli config validate

Checks your lifesavor-build.yml for syntax errors, missing fields, and invalid values before you push.

Check Submission Readiness

lsai-cli components status <component-id>

This shows you exactly what's missing before submission: description, category, tags, connected repo, etc. Fix everything in the checklist before running submit.

Common Issues

"Skill has no entrypoint defined" — Your skill.json is missing the entrypoint block.

"Failed to parse skill response as JSON" — Your skill is writing something other than JSON to stdout. Check for debug prints, logging to stdout, or missing newlines.

"Skill execution timed out" — Your skill took longer than 30 seconds. Optimize or increase your execution tier.

"Output exceeded 1MB limit" — Your skill is returning too much data. Paginate, summarize, or stream.

"Process exited with code 1" — Your skill crashed. Run it manually with the same input to see the error.

Test locally, fix locally, then push. Your build success rate will thank you.

How the Marketplace Review Process Works

2025-04-18T00:00:00.000Z

Every component goes through QA review before it's published. Here's what we check, common rejection reasons, and how to pass on the first try.

The Review Flow

Submit → Pending QA → In Review → Approved → Ready to Publish
                         ↓
                      Rejected → Back to Draft (fix and resubmit)

After you submit, your component enters the QA queue. A reviewer evaluates it against our checklist. If it passes, you can publish. If not, you get specific feedback on what to fix.

What We Check

Metadata Completeness

Description is clear and accurate (not just "a skill")
Category matches what the component actually does
Tags are relevant and helpful for discovery
License is specified
Compatibility platforms are listed

Manifest Validity

All required fields present and correctly typed
Version follows semver
Entrypoint command exists and is valid
Config schema (if present) is well-formed
Setup steps reference valid fields

Security

No hardcoded credentials or API keys in source
Secrets use x-secret flag properly
No unnecessary filesystem access declarations
No suspicious network calls
Dependencies are from trusted sources

Functionality

The component actually does what the description says
Error handling is reasonable (doesn't crash on bad input)
Timeouts are appropriate for the execution tier
Output is well-structured JSON

Documentation

README explains what the component does
Setup instructions are clear
If there's a usage_guide, it's helpful

Common Rejection Reasons

"Description too vague" — "A useful skill" doesn't tell users anything. Be specific: "Fetches current weather and 5-day forecasts from OpenWeatherMap for any city worldwide."

"Missing error handling" — If your skill crashes on invalid input instead of returning a structured error response, it'll be rejected. Always return {"status": "failed", "error": "..."} instead of crashing.

"Hardcoded credentials" — Any API key, token, or secret in your source code is an automatic rejection. Use config_schema with x-secret.

"Execution tier mismatch" — If your skill makes external API calls but uses tier 1 (most restricted), it may timeout. Match your tier to your actual resource needs.

"No validation on required config" — If your skill requires an API key but doesn't validate it during setup, users will get cryptic errors later. Add a validation_command.

How to Pass on the First Try

Run lsai-cli skill config validate — catches manifest issues before submission
Test in the sandbox — if it works in the sandbox, it'll work in production
Write a real description — 2-3 sentences explaining what it does and who it's for
Handle errors gracefully — never crash, always return structured error responses
Use x-secret for credentials — no exceptions
Include a README — even a short one helps
Test with bad input — what happens when the API key is wrong? When the network is down? When input is empty?

After Rejection

Rejections include specific feedback. Fix the issues, then resubmit:

lsai-cli components submit <component-id>

You don't need to create a new component — just fix and resubmit the same one. Your draft is preserved.

Timeline

Reviews typically complete within 1-2 business days. Complex components (models, system components) may take longer. You'll get a notification when the review is complete.

Why We Chose Rust for a Cross-Platform Agent

2025-04-16T00:00:00.000Z

The Life Savor agent runs on macOS, Windows, six Linux distributions, NetBSD, and OpenBSD — all from a single codebase. We chose Rust for this, and it wasn't because Rust is trendy. Here's the actual reasoning.

The Requirements

We needed a language that could:

Compile to a single native binary (no runtime dependencies)
Run on every major desktop OS without a VM or interpreter
Handle concurrent WebSocket connections, model inference, and skill execution simultaneously
Manage memory safely without a garbage collector (predictable latency for real-time inference)
Interface with native platform APIs (Keychain on macOS, Credential Manager on Windows, libsecret on Linux)
Embed PyTorch and ONNX Runtime for local model inference

What We Considered

Go — great for servers, but CGo makes cross-compilation painful. Embedding PyTorch via CGo is fragile. The garbage collector introduces latency spikes during inference.

C++ — meets all technical requirements, but memory safety is manual. For a security-critical application handling PII, encrypted vaults, and sandboxed processes, we didn't want to bet on manual memory management.

Node.js / Python — require a runtime. Distributing a Node.js app as a native binary means bundling the entire runtime. Performance for local inference is inadequate.

Swift — excellent on Apple platforms, but cross-platform support is limited. We use Swift for the macOS-native GUI, but the core agent needs to run everywhere.

Rust — single binary, no runtime, memory safety enforced at compile time, excellent async ecosystem (tokio), first-class C FFI for PyTorch/ONNX, and compiles to every target we need.

What Rust Gives Us

Zero-Cost Abstractions for the Pipeline

The message interception pipeline processes every message through PII scanning, content safety, and routing. In Rust, this pipeline is a chain of zero-cost abstractions — no heap allocations in the hot path, no virtual dispatch overhead, no garbage collection pauses.

Fearless Concurrency

The agent juggles:

A persistent WebSocket connection (heartbeats, commands)
Multiple skill processes (spawned, monitored, terminated)
Model inference (potentially GPU-bound)
File system watchers (skill directory changes)
Encrypted vault operations

Rust's ownership system prevents data races at compile time. We don't need mutexes around everything — the type system tells us when shared state is safe.

Cross-Compilation

We build for 8+ targets from a single CI pipeline:

x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
x86_64-apple-darwin
aarch64-apple-darwin
x86_64-pc-windows-msvc
x86_64-unknown-netbsd
x86_64-unknown-openbsd

Each produces a single static binary. No installer dependencies, no shared libraries to manage, no "works on my machine" issues.

Safe FFI for ML Runtimes

The agent embeds PyTorch (via tch-rs) and ONNX Runtime (via ort). These are C/C++ libraries with complex memory management. Rust's FFI boundary gives us safe wrappers — if we misuse the C API, the compiler catches it.

The Tradeoffs

Compile times. A full release build takes 5-8 minutes. Incremental debug builds are fast, but CI pipelines feel the cost.

Learning curve. The borrow checker is real. New contributors take longer to become productive. But once code compiles, it tends to work correctly — fewer runtime bugs, fewer production incidents.

Ecosystem maturity. Some libraries are younger than their Go/Node equivalents. We've contributed patches upstream and occasionally vendor dependencies.

Binary size. A release binary with PyTorch and ONNX Runtime linked is ~50MB. Acceptable for a desktop application, but larger than a Go binary would be.

Would We Choose It Again?

Yes. The combination of memory safety, native performance, cross-platform compilation, and safe C FFI is unique to Rust. For a security-critical application that runs on user devices, handles sensitive data, and embeds ML runtimes — there isn't a better option today.

The agent has been running in production across all supported platforms with zero memory-safety-related bugs. The type system catches those at compile time, so they never reach users.

The Case for Local-First AI

2025-04-14T00:00:00.000Z

The default assumption in AI today is that your data goes to the cloud. You type a message, it travels to a data center, gets processed on someone else's GPU, and the response comes back. This works, but it comes with costs that most people don't think about until it's too late.

We think the future is local-first. Here's why.

The Cloud Model's Hidden Costs

Privacy is a promise, not a guarantee. When your data leaves your device, you're trusting the provider's security, their employees, their subprocessors, and their government's legal framework. One breach, one subpoena, one rogue employee — and your private conversations are exposed.

Latency is variable. Cloud inference depends on network conditions, server load, and queue depth. A request that takes 200ms today might take 2 seconds tomorrow during peak hours. Local inference is consistent.

Availability is someone else's problem. When OpenAI has an outage, your AI stops working. When your local model is loaded, it works regardless of what's happening on the internet.

Cost scales with usage. Every token costs money. Heavy users pay hundreds per month. Local inference is free after the initial model download — your electricity bill is the only ongoing cost.

You don't own the relationship. The provider can change pricing, deprecate models, alter behavior, or shut down entirely. Your workflows break when their business decisions change.

What Local-First Means

Local-first doesn't mean local-only. It means:

Computation happens on your device by default. Your data doesn't leave unless you explicitly choose a cloud model.
The system works offline. No internet? No problem. Your local models, your skills, your conversations — all available.
Cloud is an option, not a requirement. When you need frontier-level capability, you can opt into cloud models. But it's your choice, not the default.
Your data is yours. Stored locally, encrypted, under your control. No training on your conversations, no data mining, no third-party access.

The Hardware Inflection Point

Three years ago, running a useful language model locally required a $10,000 GPU. Today:

A MacBook with 16GB unified memory runs a 7B model comfortably
A gaming PC with an RTX 4070 runs a 13B model at interactive speeds
Quantized models (4-bit) cut memory requirements in half with minimal quality loss
Apple Silicon's unified memory architecture makes local inference surprisingly fast

The hardware is here. The models are here (LLaMA, Mistral, Phi, Qwen — all open-source, all capable). What's been missing is the software layer that makes local AI as easy to use as cloud AI.

The Hybrid Future

We don't think cloud AI is going away. Frontier models will always push the boundaries of what's possible, and they'll always require more compute than a laptop can provide.

But for 80% of daily AI use — drafting emails, summarizing documents, answering questions, managing tasks — a local 7B model is more than sufficient. It's faster, cheaper, more private, and more reliable than a cloud API.

The right architecture supports both: local by default, cloud when you need it, with a privacy layer that protects you regardless of which path your data takes.

What This Means for Developers

If you're building on the Life Savor platform, this philosophy shapes everything:

Skills run locally in a sandbox on the user's device
Models can be local or cloud — your component works either way
User data is protected by the interceptor regardless of where inference happens
Offline support is expected — don't assume internet connectivity

Build for local-first, and your components work everywhere. Build for cloud-only, and you've limited your audience to users who are always online and willing to send their data elsewhere.

The Bet

We're betting that users will increasingly choose privacy, reliability, and control over convenience. That as local hardware gets more capable and open-source models get better, the gap between local and cloud will narrow to the point where most people don't need the cloud for everyday AI.

That future is closer than most people think. And we're building the platform for it.

MCP: What It Is and Why It Matters for AI Tooling

2025-04-12T00:00:00.000Z

MCP — the Model Context Protocol — is an open standard for connecting AI models to external tools and data sources. If you've used the Life Savor Developer MCP Server, you've already used it. But what is it, and why does it matter?

The Problem MCP Solves

Every AI model needs access to external information. A coding assistant needs to read files. A customer support bot needs to query a database. A research agent needs to search the web.

Before MCP, every integration was custom. Each AI platform had its own plugin format, its own API conventions, its own way of describing tools. If you built a tool for ChatGPT, you couldn't use it with Claude. If you built one for Claude, it didn't work with Gemini.

MCP standardizes this. One protocol, one format, works everywhere.

How It Works

MCP defines three things:

Tools — actions the AI can take. "Search the database," "create a file," "send an email." Each tool has a name, description, and input schema (what parameters it accepts).

Resources — data the AI can read. Documentation pages, configuration files, database records. Read-only access to information.

Prompts — reusable prompt templates for common workflows. "Explain this error," "review this code," "summarize this document."

The AI model connects to an MCP server, discovers what tools/resources/prompts are available, and uses them as needed during a conversation.

The Wire Format

MCP uses JSON-RPC over standard transports (stdio, SSE, HTTP). A tool call looks like:

{
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "how to validate a manifest"
    }
  }
}

The server responds with the result:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "To validate a manifest, use lsai-cli skill config validate..."
      }
    ]
  }
}

Simple, structured, language-agnostic.

Why It Matters

For developers: Build a tool once, use it with any MCP-compatible AI. Your Life Savor skill can also be exposed as an MCP tool. Your MCP server works with Claude Desktop, VS Code, Cursor, Windsurf, and any future client that supports the protocol.

For users: More tools available, better integrations, less vendor lock-in. When tools are standardized, the ecosystem grows faster.

For the ecosystem: A shared protocol means shared tooling. Debugging tools, testing frameworks, and documentation all benefit from standardization.

MCP in Life Savor

We use MCP in two ways:

1. The Developer MCP Server — a hosted service that gives developers IDE-integrated access to platform tools (scaffolding, validation, build management, documentation search). Connect from any MCP client and manage your components without leaving your editor.

2. Skills can use MCP transport — instead of raw JSON stdin/stdout, skills can implement the MCP protocol for richer tool definitions and capability discovery. The agent performs a capability handshake and invokes tools via MCP's JSON-RPC format.

Getting Started with MCP

If you want to build an MCP server (for any purpose, not just Life Savor):

Pick a transport (stdio for local tools, SSE/HTTP for hosted services)
Define your tools with names, descriptions, and JSON Schema inputs
Implement the tools/call handler
Connect from any MCP client

The protocol is open and well-documented. You don't need permission or a platform account to build an MCP server — it's a standard anyone can implement.

The Bigger Picture

MCP is doing for AI tools what REST did for web APIs — creating a shared language that lets different systems work together. We're early in this standardization, but the direction is clear: AI tooling is converging on open protocols rather than proprietary plugin formats.

We're building on that foundation because we believe open standards create better ecosystems than walled gardens.

Pass-Through Config: How User Settings Reach Your Skill at Runtime

2025-04-10T00:00:00.000Z

When a user configures your skill through the setup wizard, those values need to reach your code at runtime. This is pass-through config — the mechanism that takes user-provided settings, stores them securely, and delivers them to your skill every time it's invoked.

The Flow

User fills setup wizard
    ↓
Platform validates values (via your validation_command)
    ↓
Secrets → encrypted vault | Plain values → config.json
    ↓
User invokes your skill
    ↓
Agent resolves secrets from vault + merges config
    ↓
Your skill receives the full config in the request payload

What Your Skill Receives

Every invocation includes the user's config alongside the operation and payload:

{
  "operation": "fetch_data",
  "payload": {
    "query": "latest reports"
  },
  "config": {
    "api_key": "sk-live-abc123def456",
    "workspace_id": "ws-789",
    "max_results": 25,
    "notify_on_error": true
  }
}

Notice that api_key is the actual resolved value — not a vault reference. The agent handles decryption and resolution before your skill ever sees it. Your code just reads request.config.api_key and uses it.

How Secrets Are Handled

Fields marked with "x-secret": true in your config_schema get special treatment:

Storage: The value is encrypted with AES-256-GCM and stored in the local vault — never in plaintext on disk.
UI: Shown as •••••••• after initial entry. Users can update but never view the stored value.
Logging: Never appears in logs, error messages, or debug output.
Resolution: At invocation time, the agent decrypts the value and passes it to your skill in the config object.
Sandbox: The secret is in the JSON payload on stdin — it's never set as an environment variable (which could leak via /proc on Linux).

Your skill doesn't need to know about the vault, encryption, or key management. You declare x-secret, and the platform handles the rest.

Config Override at Install Time

When a skill is installed from the marketplace, the platform can provide config overrides — default values or organization-wide settings that merge with the user's choices:

{
  "config_override": {
    "api_key_source": "vault",
    "default_region": "us-east-1"
  }
}

These overrides merge into the skill's config.json at install time. User-provided values (from the setup wizard) take precedence over overrides.

Updating Config After Install

Users can reconfigure your skill at any time through the platform UI. When they do:

The setup wizard re-renders with current values (secrets shown as masked)
User changes what they want
Validation commands run again (if defined)
New values are persisted
Next invocation uses the updated config

Your skill doesn't need to handle config reloading — it gets the current config on every invocation. Stateless by design.

Accessing Config in Your Code

Node.js

const readline = require('readline');
const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const request = JSON.parse(line);
  const { operation, payload, config } = request;

  // Use config values directly
  const apiKey = config.api_key;
  const maxResults = config.max_results || 10;

  // Your logic here...
});

Python

import json
import sys

for line in sys.stdin:
    request = json.loads(line.strip())
    config = request.get("config", {})

    api_key = config["api_key"]
    max_results = config.get("max_results", 10)

    # Your logic here...

Rust

#[derive(Deserialize)]
struct SkillRequest {
    operation: String,
    payload: serde_json::Value,
    config: SkillConfig,
}

#[derive(Deserialize)]
struct SkillConfig {
    api_key: String,
    max_results: Option<u32>,
}

Best Practices

Don't cache config across invocations. Your skill is a short-lived process — read config from the request every time. This ensures you always have the latest values.

Validate config in your validation_command, not at runtime. By the time your skill is invoked, config should already be valid. The setup wizard catches errors early.

Use defaults in your schema. If a field has a sensible default, declare it. Users who don't customize still get working behavior.

Don't log secrets. Even though the agent redacts them from its own logs, your skill's stderr output might be captured. Never print config values that could be sensitive.

Handle missing optional fields gracefully. Not every field will be present — use defaults in your code for anything not in required.

The Security Model

The pass-through config system is designed so that:

Secrets are encrypted at rest (vault)
Secrets are decrypted only at invocation time (just-in-time resolution)
Secrets are passed via stdin (not environment variables)
The skill process is sandboxed (can't read other skills' configs)
Config is scoped per-user, per-skill (no cross-contamination)

You get the convenience of "just read the config object" with the security of encrypted vault storage. No key management code in your skill, no credential files to protect, no rotation logic to implement.