Plugin Author Quickstart

Plugin Author Quickstart

ɳSelf plugins are microservices that run alongside the main stack. The CLI installs, starts, stops, and monitors them. Each plugin exposes a REST API and declares a schema (Postgres tables in the np_<name> schema).

Four SDKs are available. Pick the one that matches your stack.

Language	Install	Runtime
Go (recommended)	go get github.com/nself-org/cli/sdk/go	native binary
TypeScript	pnpm add @nself/plugin-sdk	Bun
Python	pip install nself-plugin-sdk	Python 3.10+
Flutter/Dart	flutter pub add nself_sdk	Dart 3+

---

Before you start

Install the ɳSelf CLI and verify it is running:

nself version
nself start --check

---

Option A: Go plugin (recommended)

Go is the default language for ɳSelf plugins. Use Go unless you have a specific reason to use TypeScript (existing TS codebase, Deno edge runtime).

1. Install the SDK

go get github.com/nself-org/cli/sdk/go@latest

The SDK gives you: lifecycle management, structured logging, config loading, HTTP server with /healthz and /metrics, Postgres pool helpers, license gating, and a test harness. No boilerplate.

2. Scaffold a plugin

mkdir my-plugin && cd my-plugin
go mod init github.com/yourname/my-plugin

cat > plugin.go << 'GOEOF'
package main

import (
    "net/http"
    sdkplugin  "github.com/nself-org/cli/sdk/go/plugin"
    sdkserver  "github.com/nself-org/cli/sdk/go/server"
    sdklogger  "github.com/nself-org/cli/sdk/go/logger"
)

func main() {
    log := sdklogger.New("my-plugin", "0.1.0")
    srv := sdkserver.New(sdkserver.Config{Port: 3900})
    srv.Handle("/my-plugin/hello", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"ok": true}`))
    }))
    sdkplugin.Run(srv, sdkplugin.Info{
        Name:    "my-plugin",
        Version: "0.1.0",
        Logger:  log,
    })
}
GOEOF

3. Write plugin.yaml

The manifest declares your plugin to the ɳSelf registry.

name: my-plugin
version: 0.1.0
tier: free               # or: pro
license: MIT
description: One sentence summary.
author: yourname
port: 3900
schema: np_my_plugin     # Postgres schema (created automatically on install)
health: /my-plugin/healthz
endpoints:
  - GET /my-plugin/hello
systemDependencies: []   # postgres, redis, minio, etc.
depends: []              # other plugin names
env:
  MY_PLUGIN_SECRET:
    required: false
    description: Optional secret token
    default: ""

4. Run locally

go run plugin.go
curl http://localhost:3900/my-plugin/hello

5. Install into your ɳSelf stack

nself plugin install ./my-plugin
nself build && nself start

---

Option B: TypeScript plugin

Use nself for TypeScript plugins (Bun runtime).

1. Install the SDK

pnpm add @nself/plugin-sdk

2. Scaffold

index.ts

import { createPlugin } from '@nself/plugin-sdk'

const app = createPlugin({
  name: 'my-plugin',
  version: '0.1.0',
  port: 3900,
})

app.get('/my-plugin/hello', (c) => c.json({ ok: true }))

app.start()

Minimal plugin.yaml is identical to the Go version above. Change runtime: bun at top level.

---

Option C: Python plugin

Use Python 3.10+ for data-heavy plugins, ML inference, or when your team already has a Python codebase.

1. Install the SDK

pip install nself-plugin-sdk

2. Scaffold

main.py

from nself_sdk import create_plugin, JSONResponse

app = create_plugin(name="my-plugin", version="0.1.0", port=3900)

@app.get("/my-plugin/hello")
async def hello():
    return JSONResponse({"ok": True})

if __name__ == "__main__":
    app.run()

Minimal plugin.yaml is identical to the Go version above. Change runtime: python at top level.

---

Option D: Flutter/Dart plugin

Use Dart for plugins that ship as companion widgets alongside a Flutter app (e.g., a plugin that renders UI inside the ɳClaw or nChat app).

1. Install the SDK

flutter pub add nself_sdk

Or add directly to pubspec.yaml:

dependencies:
  nself_sdk: ^1.0.0

2. Scaffold

lib/main.dart

import 'package:nself_sdk/nself_sdk.dart';

void main() async {
  final app = NselfPlugin(name: 'my-plugin', version: '0.1.0', port: 3900);

  app.get('/my-plugin/hello', (req) async {
    return Response.json({'ok': true});
  });

  await app.run();
}

Minimal plugin.yaml is identical to the Go version above. Change runtime: dart at top level.

---

Plugin manifest reference

Field	Required	Notes
name	yes	Lowercase, hyphens only
version	yes	Semver
tier	yes	free or pro
license	yes	MIT for free, nself for pro
port	yes	Unique port (see Port Registry)
schema	yes	Postgres schema. Convention: np_<name>
health	yes	Health endpoint path
endpoints	yes	Documented REST surface
depends	no	Plugins that must install first
systemDependencies	no	postgres, redis, minio, mail, search
env	no	Env vars the plugin reads

Full spec: Plugin System Spec

---

Plugin author role

Once you ship a plugin, post it in the #showcase channel on community chat at chat.nself.org to get the plugin-author role. Plugin authors get:

• Early access to SDK pre-releases
• #plugin-authors channel for SDK questions
• Listed in the community plugin registry

---

Templates

Two ready-to-clone templates are available:

# REST API plugin template
git clone https://github.com/nself-org/plugin-template-rest-api

# Webhook dispatcher template
git clone https://github.com/nself-org/plugin-template-webhook-dispatcher

Each template includes: plugin.yaml, Go source, Dockerfile, tests, and a GitHub Actions CI workflow.

---

Publishing

Free plugins go to nself-org/plugins. Open a PR with:

• free/<your-plugin>/plugin.yaml
• free/<your-plugin>/README.md
• At least one passing test

Pro plugins are published through the ɳSelf Pro Plugin Program.