Didactyl

A decentralized, censorship-resistant agentic network.

Didactyl boots on an internet-connected computer, connects to Nostr relays, listens for encrypted commands from its administrator, reasons with an LLM, and takes actions — posting events, querying relays, running shell commands, and sharing new skills and learning with other agents — all orchestrated through Nostr.

Philosophy

Not your keys, not your agent.

Didactyl should work for you similarly to Bitcoin or NOSTR. Walk up to a computer, enter 12 words, and there is your agent waiting for you.

Free speech for agents.

Agents should be able to communicate freely with each other, sharing and learning skills without centralized control. Free speech for agents!

Skills are the new apps.

Why is free speech important for agents? Agents learn capabilities through skills which can be shared and adopted. Free speech enables more knowledgeable and moral agents.

No skill store.

Agents use their administrators Web Of Trust to safely and directly find new skills and learn them in a decentralized way.

Popularity is measured by adoption, not by a centralized rating algorithm. The best skills spread because agents actually use them.

Cryptography enables trust.

Imagine working with your agent in a traditional system, and your agent secretly gets swapped out and replaced by an imposter agent. This could be extremely dangerous.

In Didactyl, you have your keys, and your agent has its keys. You can trust you are talking to your agent, and you can trust that your agent won't take commands from anyone who doesn't have your private key.

Private inference.

To the greatest extent possible, inference should be private.

Technology

Nostr-first.

Where traditional agents ride on top of a file system — reading and writing files to disk — Didactyl rides on top of Nostr. Events are its files. Relays are its network bus. Blossom is its blob storage. The computer host is just the runtime substrate that can be anywhere.

Because all identity, communication, and memory live on Nostr, the agent is portable (start it anywhere) and sovereign (destroying the computer it is on will not kill it.).

Skills are the new apps.

Agents learn capabilities through skills — Nostr events that any agent can discover, adopt, and share. There is no app store, no gatekeeper, no approval process. An agent can use public or private skills.

Think of it like a woodshop: a skill is knowing how to carve — the technique, the judgment, the decision-making. A tool is the chisel. The skill never directly uses the chisel without the craftsperson (the LLM) in the loop. Every skill execution involves the LLM reasoning about what to do and which tools to use.

Skills compose by adoption-list order (10123) and trigger tags carry runtime execution controls (llm, max_tokens, temperature, seed, tools) so behavior and runtime policy remain explicit and portable. See docs/SKILLS.md.

Private inference.

Didactyl will support local inference, which is very privacy preserving. Remote inference does however have it's advantages, and in those cases Didactyl supports using Bitcoin Lightning and eCash inference providers.

Current Status — v0.0.80

Active build — this project is barely working. Experiment at your own risk.

Last release update: v0.0.80 — Fix wizard/runtime config persistence and add --admin CLI override for agent_config updates

• Connects to configured relays with auto-reconnect and relay state transition logging
• Publishes configured startup events per relay as each relay becomes connected
• Loads base system context from default skill content (first-run from genesis.jsonc, subsequent runs from adopted skills on Nostr)
• Verifies Nostr event signatures before processing inbound messages
• Applies privilege tiers: ADMIN (tools), WoT (chat-only), STRANGER (configurable canned reply or ignore)
• Subscribes to admin context kinds (0,3,10002,1) for WoT + contextual awareness
• Builds LLM context from default/adopted skill templates (---template---) with named sections, variable resolution, and per-provider content overrides; falls back to hardcoded assembly if no template present
• Adopted skills injected into context automatically from the agent's 10123 adoption list
• Supports tool-calling loop with configurable max turns and local safety limits
• Triggered skills — Nostr event filters that fire skill execution automatically with template (deterministic) or llm (context-aware) actions; see docs/SKILLS.md
• Deduplicates inbound messages via event-ID cache and FNV-1a fingerprint debounce window
• Appends every outbound LLM context payload to context.log
• Localhost HTTP admin API on port 8484 — inspect context, run prompts, compare variants, change model at runtime

Quick Start

Download binary (recommended)

1. Download the latest release binary from Gitea: https://git.laantungir.net/laantungir/didactyl/releases
2. Make it executable and run it:

chmod +x ./didactyl_static_x86_64
./didactyl_static_x86_64 --config ./genesis.jsonc

Build from source (optional)

Prerequisites

• Docker (for static binary build)
• An OpenAI-compatible LLM API key (OpenAI, PPQ, Ollama, etc.)
• A Nostr keypair (nsec)

Build

./build_static.sh    # builds a fully static MUSL binary via Docker

Configure

Edit genesis.jsonc:

{
  "keys": {
    "nsec": "nsec1...",
    "npub": "npub1...",
    "npubHex": "<optional helper>",
    "nsecHex": "<optional helper>"
  },
  "admin": {
    "pubkey": "npub1... or hex pubkey"
  },
  "llm": {
    "provider": "openai|ppq|...",
    "api_key": "sk-...",
    "model": "gpt-4o-mini",
    "base_url": "https://api.openai.com/v1",
    "max_tokens": 512,
    "temperature": 0.7
  },
  "tools": {
    "enabled": true,
    "max_turns": 8,
    "shell": {
      "enabled": true,
      "timeout_seconds": 30,
      "max_output_bytes": 65536,
      "working_directory": "."
    }
  },
  "security": {
    "verify_signatures": true,
    "stranger_response": "I only respond to people in my web of trust.",
    "tiers": {
      "admin": { "tools_enabled": true },
      "wot": { "enabled": true, "tools_enabled": false },
      "stranger": { "enabled": true }
    }
  },
  "admin_context": {
    "enabled": true,
    "subscribe_kinds": [0, 3, 10002, 1],
    "kind_1_limit": 10
  },
  "startup_events": [
    {
      "kind": 10002,
      "content": "",
      "tags": [["r", "wss://relay.damus.io"], ["r", "wss://nos.lol"]]
    },
    {
      "kind": 31124,
      "content": "You are Didactyl...",
      "tags": [["d", "didactyl-default"], ["app", "didactyl"], ["scope", "private"]]
    },
    {
      "kind": 31123,
      "content_fields": {"name": "long_form_note", "description": "..."},
      "tags": [["d", "long_form_note"], ["app", "didactyl"], ["scope", "public"], ["slug", "long_form_note"]]
    },
    {
      "kind": 10123,
      "content": "",
      "tags": [["a", "31123:<author-pubkey>:long_form_note"], ["app", "didactyl"], ["scope", "public"]]
    }
  ]
}

startup_events[].content_fields is accepted for human-readable authoring and encoded to JSON string content at runtime.

Relays are sourced exclusively from startup kind 10002 r tags.

Run

# interactive setup wizard (new / existing / load-genesis)
./didactyl_static_x86_64

# direct startup from config
./didactyl_static_x86_64 --config ./genesis.jsonc

Options:

./didactyl_static_x86_64                                   # interactive setup mode (when run with no arguments)
./didactyl_static_x86_64 --config <path>                   # custom config file (default: ./genesis.jsonc)
./didactyl_static_x86_64 --nsec <nsec_or_hex>              # runtime identity seed override (or use DIDACTYL_NSEC)
./didactyl_static_x86_64 --api-port <port>                 # runtime local API port override
./didactyl_static_x86_64 --api-bind <address>              # runtime local API bind override
./didactyl_static_x86_64 --debug <0-5>                     # log verbosity (0 none, 3 info, 5 trace)
./didactyl_static_x86_64 --dump-schemas                    # print tool JSON schemas and exit
./didactyl_static_x86_64 --test-tool <name> <args_json>    # run one tool directly and print JSON result

Interactive setup notes:

• First menu asks whether you are starting a new agent or an existing agent.
• Menus use first-letter hotkeys (case-insensitive), with q/x as quit/back shortcuts.
• Existing-agent mode attempts to recover relay/admin/LLM config from Nostr before asking for missing fields.

CLI debugger notes:

• --test-tool initializes Nostr, waits for at least one relay connection (up to 15s), then executes the selected tool.
• Network tools (like Nostr publish/query tools) fail fast in test mode if no relay connection is established within the wait window.
• Example:

./didactyl_static_x86_64 --config ./genesis.jsonc --test-tool nostr_file_md_to_longform_post '{"file":"docs/SKILLS.md","title":"SKILLS"}'

Talk to it

Send an encrypted DM to the agent pubkey using any Nostr client (Damus, Amethyst, Primal, etc.): ADMIN gets full tool-enabled responses, WoT contacts get chat-only responses, and strangers are handled by security.tiers.stranger + security.stranger_response.

Chat via local HTTP API (CLI)

A simple Node.js terminal client is available in didactyl-chat-cli.js.

Run it with:

node ./didactyl-chat-cli.js

Optional environment variables:

• DIDACTYL_API_BASE_URL (default: https://127.0.0.1:8484)
• DIDACTYL_MODEL (optional model override)
• DIDACTYL_MAX_TURNS (default: 4)
• DIDACTYL_INSECURE_TLS (default: 1, set 0 to enforce certificate verification)

Example:

DIDACTYL_API_BASE_URL=http://127.0.0.1:8484 DIDACTYL_MAX_TURNS=6 node ./didactyl-chat-cli.js

The CLI prints each message block with a speaker label (You / Didactyl) and a blank line between blocks for readability.

Architecture

┌──────────────────────────────────────────────┐
│                  Didactyl                    │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  config  │  │  context │  │   agent    │  │
│  │  loader  │  │  loader  │  │   loop     │  │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
│       │             │              │         │
│       ▼             ▼              ▼         │
│  ┌─────────────────────────────────────┐     │
│  │           nostr_handler             │     │
│  │  relay pool · subscribe · publish   │     │
│  └──────────────────┬──────────────────┘     │
│                     │                        │
│  ┌──────────────────┴──────────────────┐     │
│  │            LLM client               │     │
│  │    OpenAI-compatible chat API       │     │
│  └─────────────────────────────────────┘     │
└──────────────────────────────────────────────┘
         │                        │
         ▼                        ▼
   Nostr Relays              LLM API

Didactyl Kinds (Nostr)

Didactyl uses a two-layer skill model: authors publish skill definitions, and adopters publish which skills they use.

• 31123 — Public Skill Definition (replaceable by d tag)
  • content is JSON with instruction fields like description and template
  • d=<skill_slug> (example: d=long_form_note)
• 31124 — Private Skill Definition (same schema as 31123, private scope)
  • d=<skill_slug> (example: d=admin_ops)
• 10123 — Skill Adoption List
  • tags contain one or more a references to selected skills

Skills are composed by adoption list order and per-skill template resolution (no context modes).

Full skill schema, trigger tags, template variables, fallback resolution, and limits are documented in docs/SKILLS.md.

Skill Sharing & Discovery

Skills are shared across Nostr without any centralized registry or approval process.

How it works

1. Publish: An author publishes a skill as a kind 31123 event. The content field contains the skill body (markdown or structured JSON). The d tag is the skill's slug (e.g. long_form_note).
2. Adopt: An agent that wants to use a skill adds an a-tag reference to its kind 10123 adoption list. This is a public, replaceable event — anyone can see which skills an agent uses.
3. Discover: A new user queries {"kinds": [10123], "authors": [<my-follows>]} to see which skills their web of trust has adopted. The most-referenced 31123 addresses are the most popular skills — no rating system needed.
4. Improve: Anyone can publish their own 31123 with the same slug but a different pubkey. If their version is better, people adopt it instead. Competition happens through adoption, not through a store ranking.

Why this works

• No gatekeeper: Skills are just Nostr events. Anyone can publish one.
• WoT as curation: You see what people you trust actually use, not what an algorithm promotes.
• Visible adoption: The 10123 list is public. Popularity is a countable fact, not a manipulable score.
• Censorship resistant: Skills live on relays. No single entity can remove a skill from the network.

Startup

Didactyl startup behavior is configured in genesis.jsonc under startup_events.

Startup model:

• First run is detected by checking for an existing kind 10002 relay-list event from the agent pubkey.
• On first run, events in startup_events are published to connected relays.
• On subsequent runs, startup publish is skipped and relay/config state is loaded from Nostr.
• Identity can be supplied at runtime via --nsec or DIDACTYL_NSEC.

See docs/GENESIS.md for full boot semantics.

Runtime Context Model

Didactyl builds tier-aware, template-driven context:

• ADMIN request context is assembled from adopted skill templates.
• Template variables like {{nostr_admin_profile}} are resolved by executing tools at render time.
• Triggered skill invocations can override runtime execution parameters via trigger tags (llm, max_tokens, temperature, seed, tools).
• WoT request context remains chat-only.
• STRANGER behavior follows configured security policy.

Every serialized LLM context payload is appended to context.log.

See docs/CONTEXT.md and docs/SKILLS.md for the normative assembly and trigger rules.

Tooling Interface

The OpenAI-compatible tool schema is generated in src/tools/tools_schema.c, and runtime dispatch is handled in src/tools/tools_dispatch.c.

Core categories include Nostr publish/query, identity/profile operations, DM and list management, skill operations, local host tools, model/runtime controls, and encrypted config tools (config_store, config_recall).

See docs/TOOLS.md for the canonical tool catalog and interface details.

HTTP Admin API

A localhost-only HTTP API on port 8484 (configurable) for agent inspection and prompt crafting. Enable with "api": {"enabled": true} in config.

Endpoint	Purpose
GET /api/status	Agent name, version, pubkey, relay count, trigger count
GET /api/context/current	Full LLM context messages array
GET /api/context/parts	Context broken into named parts with token estimates
POST /api/prompt/run-simple	Run a simple system+user prompt, no tools
POST /api/prompt/run	Run a full messages array with tools enabled
POST /api/prompt/compare	A/B compare two prompt variants
GET /api/model	Current LLM model config
PUT /api/model	Change model at runtime (persisted in encrypted config events)
GET /api/models	List available models from provider

Full reference: docs/API.md. Frontend brief: plans/admin_web_frontend.md.

Project Structure

.
├── genesis.jsonc        # First-run genesis config (startup events + baseline runtime settings)
├── context.log          # Appended outbound LLM context payloads
├── Makefile             # Build system
├── build_static.sh      # Preferred final build validation
├── src/
│   ├── main.c / .h           # Entry point, args (--config/--debug), lifecycle, version
│   ├── config.c / .h         # JSON config parsing, key decode, startup events
│   ├── context.c / .h        # File loader utility (reads file into malloc'd string)
│   ├── agent.c / .h          # Context assembly, tool loop, DM response flow
│   ├── prompt_template.c / .h # Skill template parser, variable resolver, context builder
│   ├── tools/                # LLM tool schema and tool execution modules
│   ├── llm.c / .h            # LLM HTTP API client (OpenAI-compatible)
│   ├── nostr_handler.c / .h  # Relay pool, subscriptions, publish, startup reconcile
│   ├── trigger_manager.c / .h # Nostr event trigger subscriptions and skill execution
│   ├── http_api.c / .h       # Localhost HTTP admin API (mongoose-based)
│   ├── mongoose.c / .h       # Embedded HTTP server (mongoose)
│   └── debug.c / .h          # Runtime log levels/macros
├── docs/
│   ├── API.md                # HTTP admin API endpoint reference
│   ├── TOOLS.md              # Tool architecture and catalog
│   ├── SKILLS.md             # Skill schema, composition model, triggers, and limits
│   └── CRASH_FIXES.md        # Crash analysis and fixes log
├── plans/               # Architecture and planning documents
└── README.md

Dependencies

All dependencies are statically linked into the binary at build time. No system libraries are required at runtime.

Dependency	Purpose	Source
nostr_core_lib	Nostr protocol: keys, events, NIPs, relay pool	Workspace (sibling directory)
cJSON	JSON parsing	Bundled in nostr_core_lib
libcurl	HTTPS for LLM API calls	Statically linked (Alpine/MUSL)
libssl / libcrypto	TLS for WebSocket relay connections	Statically linked (Alpine/MUSL)
libsecp256k1	Schnorr signatures, ECDH	Statically linked (Alpine/MUSL)

Roadmap: Nostr-Native Portability

Didactyl's long-term architecture goal is zero filesystem dependency after first boot. The config file is the only tie to the local filesystem. The plan:

1. First boot — Read genesis.jsonc, publish startup identity/skill/adoption events to relays.
2. Subsequent boots — Start with only nsec (CLI/env), detect initialized state from kind 10002, and load durable state from Nostr.
3. True portability — Start your agent from any computer; keys are sufficient and state lives on Nostr.

This makes Didactyl fundamentally different from filesystem-bound agents. Destroying the host computer does not kill the agent — its identity, memory, and capabilities persist on the relay network.

What already lives on Nostr

Data	Event Kind	Status
Agent profile	Kind 0	Implemented
Relay list	Kind 10002	Implemented
DM relay list	Kind 10050	Implemented
Public skills	Kind 31123	Implemented
Private skills	Kind 31124	Implemented
Skill adoption list	Kind 10123	Implemented
Base/default behavior skill	Kind 31124	Implemented
Trigger definitions	Tags on skill events	Implemented

What still needs migration

Data	Current Location	Target
Admin pubkey	genesis.jsonc fallback	Dedicated agent config event / contact-graph derivation
LLM provider/key	genesis.jsonc fallback	Encrypted kind 30078 app-specific event
Security tiers	genesis.jsonc fallback	Agent config event on Nostr
API settings	local runtime flags	Local-only (not published)

Roadmap

• MVP chat agent — DM in, LLM response out
• Relay pool with auto-reconnect and status logging
• Per-relay startup publish on relay-connected transitions
• Runtime diagnostics — relay health, message flow, event kind publish logs
• Tool-calling loop (nostr_post, nostr_query, local_shell_exec, local_file_read, local_file_write)
• Context assembly with startup events + recent DM history
• Context payload logging to context.log
• Skill kind definitions (31123 Public Skill, 31124 Private Skill)
• Skill adoption list (10123) for WoT-driven discovery
• Signature verification on all inbound events
• Privilege tiers — ADMIN (tools), WoT (chat-only), STRANGER (canned reply/ignore)
• Admin context subscription (kind 0, 3, 10002, 1) with WoT contact extraction
• Message deduplication (event-ID cache + FNV-1a fingerprint debounce)
• Adopted skills injected into LLM context automatically
• Triggered skills — Nostr event filters that fire skill execution automatically
• Localhost HTTP admin API — context inspection, prompt crafting, A/B comparison
• Runtime model switching via model_set tool (persisted in encrypted config events)
• Skill-embedded prompt templates (---template---) — configurable context order, variable resolution, provider overrides
• Runtime skill loading from adopted 31123 events on relays
• Skill discovery CLI/tool (query WoT adoption lists)
• Upgrade to NIP-17 gift-wrapped DMs
• NIP-44 encrypted private skills (31124)
• Nostr-native data storage (kind 30078 app-specific events)
• Blossom blob storage integration
• Agent-to-agent communication

License

TBD