Getting Started

This guide will walk you through setting up NeuroSim and building your first simulation plugin.

Prerequisites

Before you begin, ensure you have the following installed:

  • Go 1.21+ — For building plugins
  • Docker & Docker Compose — For running the infrastructure
  • Git — For version control

Installation

1. Clone the Repository

git clone https://github.com/NeurosimIO/neurosim.git
cd neurosim

2. Start Infrastructure

Start the required infrastructure services using Docker Compose:

docker compose up -d

This starts Apache Kafka (message backbone) and NeuroSim Core.

3. Verify Installation

Check that Core is running:

curl http://localhost:8080/health

You should receive a healthy response.

Building Your First Plugin

1. Initialize a Go Module

mkdir my-plugin && cd my-plugin
go mod init my-plugin

2. Install the SDK

go get github.com/NeurosimIO/neurosim-sdk-go

3. Implement the Plugin Interface

Create main.go with the required plugin interface:

package main

import (
    "context"
    "log"

    neurosim "github.com/NeurosimIO/neurosim-sdk-go"
)

type MyPlugin struct{}

func (p *MyPlugin) GetRegistration() neurosim.PluginRegistration {
    return neurosim.PluginRegistration{
        ID:          "my-plugin",
        Name:        "My First Plugin",
        Description: "A simple example plugin",
    }
}

func (p *MyPlugin) OnScenarioInitialize(init neurosim.ScenarioInitialize, scenario neurosim.Scenario) error {
    log.Printf("Scenario %s initialized", init.ScenarioName)
    return nil
}

func (p *MyPlugin) OnCommand(scenarioID string, command string) string {
    return "OK"
}

func (p *MyPlugin) OnScenarioMessage(msg neurosim.ScenarioMessage, scenario neurosim.Scenario) (bool, []neurosim.ScenarioMessage) {
    return true, nil
}

func (p *MyPlugin) OnStop(msgId string, stop neurosim.ScenarioStop) error {
    log.Println("Plugin stopping")
    return nil
}

func main() {
    plugin := &MyPlugin{}
    config := neurosim.DefaultConfig()

    runner, err := neurosim.NewPluginRunner(plugin, config)
    if err != nil {
        log.Fatalf("Failed to create runner: %v", err)
    }

    if err := runner.Run(context.Background()); err != nil {
        log.Fatalf("Plugin error: %v", err)
    }
}

4. Run Your Plugin

go run main.go

Your plugin will register with NeuroSim Core and begin listening for scenario commands.

Configuration Schema

Plugins can define a JSON Schema that describes their configuration. This schema is used by the Universal UI to automatically generate configuration forms — no custom UI code required.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "My Plugin Configuration",
  "type": "object",
  "properties": {
    "instanceCount": {
      "type": "integer",
      "description": "Number of instances to simulate",
      "default": 1,
      "minimum": 1
    },
    "updateFrequency": {
      "type": "number",
      "description": "Update frequency in milliseconds",
      "default": 1000
    }
  },
  "required": ["instanceCount"]
}

Next Steps