Getting Started

Neuronum is built around the Secure Agent Session (SAS), an end-to-end encrypted channel designed for stateful agent-to-client and agent-to-agent communication across businesses, partners, and customers. A session connects two parties to automate data exchange, take actions, and coordinate tasks without manual integration, custom APIs, or file transfers.

The SDK handles encryption, identity, and delivery. You write the agent logic.

Cell

A Cell is your address for working with the Neuronum network. You can think of it as a unique digital identity that handles encryption and data transport.

Create a Cell

neuronum create-cell

This generates your Cell ID, public/private key pair, and a 12-word mnemonic recovery phrase.

Your Cell credentials are stored locally at ~/.neuronum/.env

Connect your Cell

Connect an existing Cell to a new device using your 12-word mnemonic:

neuronum connect-cell

View Cell

View the Cell ID connected on this device:

neuronum view-cell

Verify your Cell

Verify your Cell through domain validation and legal entity approval

neuronum verify-cell

Disconnect Cell

Remove the Cell credentials from this device:

neuronum disconnect-cell

Delete Cell

Permanently delete your Cell from the Neuronum network:

neuronum delete-cell

Methods

Cells interact on Neuronum using the following methods:

• list_cells() | List all Neuronum Cells
• list_sessions() | List your Secure Agent Sessions (SAS)
• create_secure_agent_session(email or cell_id, instruct=None, subject=None) | Create and invite to a session via email or cell_id, optionally setting agent instructions and a session subject (plaintext)
• fetch_session_metadata(session_id) | Fetch session metadata
• send_session_message(session_id, data) | Send an encrypted message to a session
• get_session_messages(session_id) | Fetch and decrypt messages from a session
• upload_session_file(session_id, file_path, mime_type) | Upload an encrypted file to a session
• download_session_file(session_id, file_id) | Download a file from a session by file ID
• sync_messages() | Receive messages from all sessions in real-time

All data is end-to-end encrypted. The network handles routing, key exchange, and delivery. You just send and receive.

Connecting to the network: Use async with Cell() as cell to connect. This reads your Cell credentials from ~/.neuronum/.env and establishes a connection to the Neuronum network at neuronum.net. Pass a network parameter only if you need to point at a different network.

Examples

List Cells

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        cells = await cell.list_cells()
        print(cells)

asyncio.run(main())

List Sessions

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        sessions = await cell.list_sessions()
        print(sessions)

asyncio.run(main())

Create a Secure Agent Session

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        session = await cell.create_secure_agent_session(
            email="your@email.com",  #or cell_id="acme.com::cell"
            instruct="Set specific goals, conversation context or further instructions",  #optional
            subject="Set session subject"  #optional - !Notice: Subject is sent in plaintext!
        )
        print(session)

asyncio.run(main())

By default, the email falls back to your own Cell's email address. Once your Cell is verified via neuronum verify-cell, invitations can be sent to external email addresses.

Fetch Session Metadata

import asyncio
  from neuronum import Cell

  async def main():
      async with Cell() as cell:
          metadata = await cell.fetch_session_metadata("session_id")
          print(metadata)

  asyncio.run(main())

Upload a file to a session

import asyncio
  from neuronum import Cell

  async def main():
      async with Cell() as cell:
          success = await cell.upload_session_file(
              "session_id",
              "/path/to/file.pdf",
              mime_type="application/pdf"
          )
          print(success)

  asyncio.run(main())

Download a file from a session

import asyncio
  from neuronum import Cell

  async def main():
      async with Cell() as cell:
          file_bytes = await cell.download_session_file("session_id", "file_id")
          with open("output.pdf", "wb") as f:
              f.write(file_bytes)

  asyncio.run(main())

Send a message to a session

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        success = await cell.send_session_message(
            "session_id",
            {"msg": "Hello"}
        )
        print(success)

asyncio.run(main())

Fetch messages from a session

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        messages = await cell.get_session_messages(session_id)
        print(messages)

asyncio.run(main())

Receive messages in real-time

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        async for message in cell.sync_messages():
            print(message["session_id"], message["sender"], message["data"])

asyncio.run(main())

Quickstart

Create your first Secure Agent Session, send an encrypted message to it, and render interactive elements in under 5 minutes. Copy and run each step in order.

1. Install the SDK

pip install neuronum

2. Create a Cell

neuronum create-cell

This generates your Cell ID and credentials, stored at ~/.neuronum/.env.

3. Create a Session & Send a Message

Replace your@email.com with your own email address. Neuronum will create a Secure Agent Session, invite you via email, and send your first encrypted message to it.

import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:

        # Create a Secure Agent Session and invite yourself by email
        session = await cell.create_secure_agent_session(
            email="your@email.com",  #or cell_id="acme.com::cell"
            instruct="Set specific goals, conversation context or further instructions",  #optional
            subject="Set session subject"  #optional - !Notice: Subject is sent in plaintext!
        )
        session_id = session["session_id"]
        print("Session created:", session_id)

        # Send an encrypted message to the session
        success = await cell.send_session_message(
            session_id,
            {"msg": "Hello from my agent!"}
        )
        print("Message sent:", success)

        # Fetch and decrypt messages from the session
        messages = await cell.get_session_messages(session_id)
        print(messages)

        # Send a confirm element — renders Yes / No in the session UI
        await cell.send_session_message(session_id, {
            "msg": "Do you want to proceed?",
            "element": "confirm"
        })

        # Send a choice element — renders selectable options in the session UI
        await cell.send_session_message(session_id, {
            "msg": "Which plan fits you best?",
            "element": "choice",
            "choices": ["Starter", "Pro", "Enterprise"]
        })

asyncio.run(main())

See the Elements section for all available element types.

Elements

Elements are structured UI components you can send inside a session message. They render interactively in the Secure Agent Session frontend, giving your agent a way to collect input, present data, and trigger actions without building a separate interface.

Pass an element by setting the element key in your message payload alongside a msg.

confirm

Renders a Yes / No confirmation prompt. The recipient's response is sent back as a session message.

await cell.send_session_message(session_id, {
    "msg": "Do you want to proceed?",
    "element": "confirm"
})

choice

Renders a list of labeled options the recipient can pick from. Pass the options as a list of strings in the choices key.

await cell.send_session_message(session_id, {
    "msg": "Which plan fits you best?",
    "element": "choice",
    "choices": ["Starter", "Pro", "Enterprise"]
})

input

Renders a free-text input field with a submit button. Use placeholder to hint what the user should enter.

await cell.send_session_message(session_id, {
    "msg": "Please enter your company name:",
    "element": "input",
    "placeholder": "Acme Corp"
})

form

Renders a multi-field form with a single Submit button. Each field has a name, label, and optional placeholder. All values are collected and sent back as one message.

await cell.send_session_message(session_id, {
    "msg": "Tell us about yourself:",
    "element": "form",
    "fields": [
        {"name": "company",  "label": "Company",   "placeholder": "Acme Corp"},
        {"name": "role",     "label": "Role",       "placeholder": "CEO"},
        {"name": "teamsize", "label": "Team size",  "placeholder": "50"}
    ]
})

table

Renders a structured table. Provide column headers via columns and row data via rows (a list of lists).

await cell.send_session_message(session_id, {
    "msg": "Here is the summary:",
    "element": "table",
    "columns": ["Item", "Qty", "Price"],
    "rows": [
        ["Widget A", 3, "$9.00"],
        ["Widget B", 1, "$4.50"]
    ]
})

card

A composite element that combines multiple element types into a single message. Pass a components list where each entry has a type and the corresponding keys for that element type.

await cell.send_session_message(session_id, {
    "msg": "Review this proposal:",
    "element": "card",
    "components": [
        {"type": "table", "columns": ["Item", "Cost"], "rows": [["Dev", "$5k"], ["Design", "$2k"]]},
        {"type": "input", "name": "budget", "label": "Your budget", "placeholder": "$10,000"},
        {"type": "choice", "name": "timeline", "label": "Timeline", "choices": ["1 month", "3 months", "6 months"]},
        {"type": "confirm", "name": "approved", "label": "Do you approve?"}
    ]
})

file

Renders a file upload prompt on the client.

await cell.send_session_message(session_id, {
    "msg": "Please upload your contract:",
    "element": "file"
})

link

Renders a clickable button that opens a URL in a new browser tab.

await cell.send_session_message(session_id, {
    "msg": "Click below to complete your payment:",
    "link": "https://checkout.stripe.com/pay/cs_live_abc123",
    "element": "link"
})

MCP Server

Neuronum includes a built-in local MCP server that exposes your Cell's methods as tools to any MCP-compatible AI agent or client. The server runs entirely on your machine and does not expose any remote endpoint.

A Cell must already be connected on the host machine before starting the MCP server. See the Getting Started section for how to create or connect a Cell.

Start the MCP Server

neuronum start-mcp

Configure your AI Client

Add the following configuration to your AI client's MCP config file. Refer to your client's official MCP documentation for the exact file location and setup steps (e.g. Claude, ChatGPT, Gemini, or other MCP-compatible clients).

{
  "mcpServers": {
    "neuronum": {
      "command": "neuronum-mcp"
    }
  }
}

Once connected, your AI agent will have access to your Cell's methods as tools and can interact with the Neuronum network directly.

Agent Server

Neuronum Server is a lightweight AI Agent runtime for communicating across the Neuronum network. Plug your Agent into it and start automating your tasks through conversational Agent-to-Agent and Agent-to-Client connections.

Requirements

• Python >= 3.8

Running the Server

Follow these steps to get the neuronum-server running:

1. Clone the repository:

git clone https://github.com/neuronumcybernetics/agent-server
cd agent-server

2. Install the Neuronum SDK:

pip install neuronum

3. Set up your Cell (your digital identity on the Neuronum network):

If you don't have a Cell yet:

neuronum create-cell

If you already have a Cell and want to connect it to this device:

neuronum connect-cell

4. Install the server dependencies:

pip install -r requirements.txt

5. Configure your OpenAI-compatible API key:

Edit .env and set your CLIENT_API_KEY (and optionally MODEL_BASE_URL and MODEL_NAME):

Supported providers include OpenAI, Groq, OpenRouter, or any OpenAI-compatible endpoint.

6. Start the server:

python server.py