stigmer

module
v0.0.72 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 4, 2026 License: Apache-2.0

README


Stigmer

Build AI agents and workflows with zero infrastructure.

Stigmer is an open-source AI agent platform. Run it locally with SQLite for development, or connect to Stigmer Cloud for production. Bring your own LLM — Anthropic, OpenAI, or Ollama. Same CLI, same SDK, same resource definitions — your choice of backend.

Quick Start

1. Install
# Homebrew (macOS/Linux)
brew install stigmer/tap/stigmer

# Or from source
git clone https://github.com/stigmer/stigmer.git
cd stigmer && make local

# Or via shell script
curl -fsSL https://raw.githubusercontent.com/stigmer/stigmer/main/scripts/install.sh | bash

This installs a single self-contained stigmer binary that embeds all required components.

2. Configure LLM Provider

Stigmer agents need an LLM to generate responses. You can pre-configure one before starting the server, or let the interactive setup guide you on first run.

Option A: Anthropic (recommended for best quality)

export ANTHROPIC_API_KEY=sk-ant-...

Option B: OpenAI

export OPENAI_API_KEY=sk-...

Option C: Ollama (free, local, offline)

brew install ollama
ollama serve
ollama pull qwen2.5-coder:7b

If you skip this step, stigmer server will prompt you to choose a provider interactively.

3. Start the Server
stigmer server

On first run, this prompts you to choose an LLM provider, auto-downloads Temporal, starts all services, and is ready on localhost:7234.

4. Deploy and Run an Agent
# Deploy from a YAML file
stigmer apply -f agent.yaml

# Execute
stigmer run support-bot "How do I reset my password?"
Managing the Server
stigmer server status   # check if running
stigmer server stop     # stop all services
stigmer server          # start again
stigmer server setup    # reconfigure LLM provider
stigmer server reset    # stop and remove all data (keeps config)

Core Concepts

Agents

An agent has instructions, optional MCP servers for tool access, and optional model configuration.

apiVersion: agentic.stigmer.ai/v1
kind: Agent
metadata:
  name: support-bot
spec:
  instructions: |
    You are a helpful customer support agent.
    Answer questions politely and accurately.
    Check GitHub issues for known problems.
  mcp_server_usages:
    - mcp_server_ref:
        kind: mcp_server
        slug: github
    - mcp_server_ref:
        kind: mcp_server
        slug: filesystem
stigmer apply -f agent.yaml
stigmer run support-bot "What's the status of issue #42?"
Workflows

Multi-step automations that chain HTTP calls, agent calls, variable assignments, conditionals, and loops. Workflows follow the CNCF Serverless Workflow DSL.

apiVersion: agentic.stigmer.ai/v1
kind: Workflow
metadata:
  name: hello-world
spec:
  description: A minimal workflow
  document:
    dsl: "1.0.0"
    namespace: examples
    name: hello-world
    version: "1.0.0"
  tasks:
    - name: set-greeting
      kind: set_vars
      task_config:
        variables:
          greeting: "Hello, World!"
          timestamp: "${now()}"
      export:
        as: "${.}"

Tasks support kind: set_vars, kind: http_call, kind: agent_call, kind: wait, and control flow via flow.then. See examples/workflows/ for more complex patterns including multi-agent orchestration and conditional branching.

stigmer apply -f workflow.yaml
stigmer run hello-world
Skills

Versioned knowledge artifacts (instructions + reference material) that agents can use. A skill is a directory with a SKILL.md file containing YAML frontmatter:

my-skill/
  SKILL.md          # Required: interface definition with YAML frontmatter
  tool.sh           # Optional: tool implementation
  README.md         # Optional: documentation
stigmer push                          # push skill from current directory
stigmer draft skill --name my-skill   # scaffold a new skill
MCP Servers

Stigmer uses the Model Context Protocol to give agents tool access. Agents can use any STDIO-based MCP server — npm packages (npx), Python packages (uvx), Go modules (go run), or Docker images.

Stigmer also ships its own MCP server that exposes platform resources to AI-powered IDEs:

stigmer mcp-server

See mcp-server/README.md for IDE configuration (Cursor, Claude Desktop, VS Code, Windsurf).

Go SDK

Define agents and workflows programmatically using a Pulumi-aligned struct args API.

package main

import (
    "fmt"
    "log"

    "github.com/stigmer/stigmer/sdk/go/agent"
    "github.com/stigmer/stigmer/sdk/go/stigmer"
)

func main() {
    err := stigmer.Run(func(ctx *stigmer.Context) error {
        a, err := agent.New(ctx, "code-reviewer", &agent.AgentArgs{
            Instructions: "Review code for best practices and security issues",
        })
        if err != nil {
            return err
        }
        fmt.Printf("Created agent: %s\n", a.Name)
        return nil
    })
    if err != nil {
        log.Fatal(err)
    }
}

See sdk/go/README.md for the full SDK reference, workflow builders, and more examples in sdk/go/examples/.

CLI Reference

Command Description
stigmer run <name> [prompt] Execute an agent or workflow
stigmer apply -f <file> Create or update resources from YAML
stigmer get <kind> <name> Get a resource
stigmer list <kind> List resources
stigmer delete <kind> <name> Delete a resource
stigmer search <query> Full-text search across resources
stigmer draft <kind> Scaffold a new resource
stigmer push Push a skill artifact
stigmer download <kind> <name> Download a resource artifact
stigmer validate -f <file> Validate a resource definition
stigmer server Start/stop/status/setup/reset for local server
stigmer mcp-server Start the Stigmer MCP server
stigmer backend Switch between local and cloud backends
stigmer config Manage CLI configuration

Local vs Cloud

Local Mode (Open Source) Cloud Mode (Stigmer Cloud)
Start with stigmer server stigmer backend set cloud
Storage SQLite (~/.stigmer/stigmer.db) Distributed (managed)
Orchestration Temporal (auto-managed) Temporal (managed)
Users Single implicit user Organizations, teams, IAM
LLM Anthropic, OpenAI, or Ollama (user's choice) Configurable
Best for Development, personal projects, air-gapped environments Team collaboration, production, governance

Resource definitions are portable across both modes. The CLI talks to the same gRPC service interfaces regardless of backend.

LLM Configuration

On first run, stigmer server guides you through an interactive setup to choose your LLM provider. The chosen provider and API key are saved to ~/.stigmer/config.yaml.

Supported providers:

Provider Model (default) Requires
Anthropic claude-sonnet-4.5 ANTHROPIC_API_KEY env var or API key in config
OpenAI gpt-4 OPENAI_API_KEY env var or API key in config
Ollama qwen2.5-coder:7b Ollama installed and running locally

Config file example (~/.stigmer/config.yaml):

backend:
  local:
    llm:
      provider: anthropic
      model: claude-sonnet-4.5

Environment variables (take precedence over config file):

export STIGMER_LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
Changing Your LLM Provider

Re-run the interactive setup:

stigmer server setup

Or set the provider directly:

stigmer config set llm.provider anthropic    # switch to Anthropic
stigmer config set llm.provider openai       # switch to OpenAI
stigmer config set llm.provider ollama       # switch to Ollama

After changing the provider, restart the server:

stigmer server stop && stigmer server

Architecture

Stigmer is a single binary (BusyBox pattern) that embeds all required services:

┌──────────────────────────────────────────────────────┐
│                  stigmer CLI (Go)                     │
│              (client-apps/cli/)                       │
└────────────────────┬─────────────────────────────────┘
                     │ gRPC (localhost:7234)
┌────────────────────▼─────────────────────────────────┐
│            stigmer-server (Go)                        │
│        (backend/services/stigmer-server/)             │
│                                                       │
│  Controllers: Agent, Workflow, Skill, MCP Server      │
│  Storage: SQLite via modernc.org/sqlite (pure Go)     │
└────────────────────┬─────────────────────────────────┘
                     │ Temporal Client
┌────────────────────▼─────────────────────────────────┐
│            Temporal (auto-managed)                     │
└───────────┬───────────────────────┬──────────────────┘
┌───────────▼──────────┐  ┌────────▼──────────────────┐
│  agent-runner        │  │  workflow-runner           │
│  (Python)            │  │  (Go)                      │
│  Graphton agent      │  │  CNCF Serverless Workflow  │
│  execution           │  │  execution                 │
└──────────────────────┘  └───────────────────────────┘

Components:

  • stigmer CLI — User-facing command-line interface with backend abstraction (local daemon vs cloud). Location: client-apps/cli/
  • stigmer-server — Go gRPC API server with SQLite storage, protobuf validation, and full-text search (FTS5). Location: backend/services/stigmer-server/
  • agent-runner — Python Temporal worker for AI agent execution via the Graphton framework. Location: backend/services/agent-runner/
  • workflow-runner — Go Temporal worker for CNCF Serverless Workflow execution with Claim Check and Continue-As-New patterns. Location: backend/services/workflow-runner/
  • Go SDK — Pulumi-aligned SDK for defining agents and workflows programmatically. Location: sdk/go/
  • MCP Server — Stateless MCP gateway bridging AI IDEs to stigmer-server via gRPC. Location: mcp-server/
  • Proto APIs — gRPC service definitions that serve as the contract between CLI and backends. Location: apis/

Development

Prerequisites
  • Go 1.25 or later
  • Python 3.11+ with Poetry (for agent-runner)
  • Git, Make
Building from Source
git clone https://github.com/stigmer/stigmer.git
cd stigmer

# Install all dependencies
make setup

# Build the CLI (outputs bin/stigmer)
make build

# Run tests
make test
Proto Generation
cd apis
make build         # generate Go + Python stubs
make lint          # lint proto files
make fmt           # format proto files

Generated stubs go to apis/stubs/ (excluded from version control). See apis/README.md for details.

Releases
make release bump=patch   # create a release tag (triggers GoReleaser via GitHub Actions)
make protos-release       # publish protos to Buf separately

See Distribution Guide for the full packaging and release process.

Troubleshooting

Server won't start:

stigmer server status              # check if already running
stigmer server stop && sleep 2 && stigmer server   # restart cleanly

Check logs:

stigmer server logs

Reset all local data:

stigmer server reset    # stops services, removes data, keeps config
stigmer server          # recreates everything on first run

To also remove configuration (API keys, LLM preferences):

stigmer server reset --include-config

Documentation

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE.

Directories

Path Synopsis
apis
stubs/go module
backend
libs/go module
client-apps
cli module
docs
sdk
mcp-server module
sdk
go module
seedpack module
test
integration module
tools module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL