DOCSEARCHbyAlgolia
Submit Docs

Shinkai Local AI Agents

repository·main·Indexed 19 days ago

https://github.com/dcspark/shinkai-local-ai-agents

An open-source platform for creating AI agents using local or remote models, featuring a no-code visual builder, multi-agent orchestration, and crypto-native capabilities. The project is an NX monorepo consisting of a Tauri-based desktop application (shinkai-desktop) and shared libraries including shinkai-message-ts, shinkai-node-state, shinkai-ui, shinkai-artifacts, and shinkai-i18n.

Tokens
81.9K
Snippets
299
Records
408
Agent score
64%

What's inside Shinkai

  1. Overview of Shinkai AI Agent Platform

    main

    Shinkai is an open-source platform designed to create powerful, collaborative AI agents using either local or remote AI models. It features a no-code, drag-and-drop visual interface, allowing users to build specialized agents without programming experience.

    Key capabilities include:

    • Multi-agent Orchestration: Deploy teams of agents that collaborate, share context, and coordinate complex workflows.
    • Crypto-native Architecture: Built-in support for decentralized payments, DeFi interactions, and autonomous economic agents.
    • Universal Protocol Support: Seamless integration with the Model Context Protocol (MCP), making agents compatible with Claude, Cursor, and the broader AI ecosystem.
    • Hybrid Deployment: Run models locally for maximum privacy or connect to cloud models for enhanced capabilities.
    • Security-first Design: Local-first architecture ensures cryptographic keys and sensitive data remain under user control.

  2. Overview of Shinkai Local AI Agents

    main

    Shinkai is a free, open-source platform designed to democratize the creation of AI agents. It allows users to build, deploy, and orchestrate intelligent agents that can collaborate, handle payments, and automate complex workflows using a no-code, drag-and-drop interface.

    Key capabilities include:

    • No-Code Agent Builder: Create specialized agents via a visual interface.
    • Multi-Agent Orchestration: Deploy teams of agents that share context and coordinate multi-step workflows.
    • Crypto-Native Architecture: Built-in support for decentralized payments, DeFi interactions, and autonomous economic agents.
    • Universal Protocol Support: Seamless integration with the Model Context Protocol (MCP), making agents compatible with Claude, Cursor, and the broader AI ecosystem.
    • Hybrid Deployment: Run everything locally for maximum privacy or connect to cloud models for enhanced capabilities.
    • Security-First Design: Local-first architecture ensures crypto keys and sensitive data remain under user control.
    • Cross-Platform: Compatible with Windows, macOS (Apple Silicon), and Linux.

  4. Overview of Shinkai AI Agents

    main

    Shinkai is an open-source platform designed to democratize the creation of powerful AI agents. It allows users to build, deploy, and manage intelligent agents that can collaborate, handle payments, and automate complex workflows using either local or remote AI models.

    Key capabilities include:

    • No-Code Agent Builder: Create specialized agents via a visual drag-and-drop interface without programming knowledge.
    • Multi-Agent Orchestration: Deploy teams of agents that share context and coordinate multi-step workflows.
    • Crypto-native Architecture: Built-in support for autonomous economic agents capable of decentralized payments and fault-tolerant interactions.
    • Universal Protocol Support: Seamless integration with MCP (Model Context Protocol) for compatibility with Claude, Cursor, and the broader AI ecosystem.
    • Hybrid Deployment: Run everything locally for maximum privacy, connect to cloud models, or use a hybrid approach.
    • Security-First Design: Local-first architecture ensures encryption keys, sensitive data, and computations remain under user control.
    • Cross-Platform: Compatible with Windows, MacOS (Apple Silicon supported), and Linux.

  5. Understand the Shinkai architecture

    main

    Shinkai is a modern monorepo built with nx. The architecture is divided into core applications and shared libraries.

    Core Application

    • Shinkai-Desktop: A cross-platform Tauri application using a React frontend.

    Shared Libraries

    • Shinkai-Message-TS: Message protocols and network communication for Shinkai nodes.
    • Shinkai-Node-State: Query-based reactive state management for node data.
    • Shinkai-ui: Reusable reactive components and design system.
    • Shinkai-Artifacts: UI primitives built on Radix and Tailwind CSS.
    • Shinkai-I18N: Internationalization utilities powered by i18next.

    Technology Stack

    • Frontend: React 18, TypeScript, Tailwind CSS, Radix UI
    • Desktop: Tauri (Rust + React)
    • State Management: Zustand (UI State) + React Query (Server State)
    • Build System: vite, nx monorepo
    • Testing: Vitest, React Testing Library

  6. Shinkai Architecture Overview

    main

    Shinkai is a modern monorepo managed by nx. The architecture is split into core applications and shared libraries:

    Core Applications

    • shinkai-desktop: A cross-platform Tauri application with a React frontend.

    Shared Libraries

    • shinkai-message-ts: Messaging protocols and network communication with Shinkai Node.
    • shinkai-node-state: Reaction-query based state management for node data.
    • shinkai-ui: Reusable reactive components and design system.
    • shinkai-artifacts: User-style primitives built on Radix UI and Tailwind CSS.
    • shinkai-i18n: Internationalization utilities powered by i18next.

    Technology Stack

    • Frontend: React 18, TypeScript, Tailwind CSS, Radix UI.
    • Desktop: Tauri (Rust + React).
    • State Management: Zustand (UI State) and React Query (Server State).
    • Build System: VITE, NX MONOREPO.
    • Testing: Vitest, React Testing Library.

  7. How Shinkai architecture works

    main

    Shinkai is a modern monorepo managed by NX. It is composed of a core desktop application and several shared libraries.

    Core Application:

    • shinkai-desktop: A cross-platform Tauri application with a React frontend.

    Shared Libraries:

    • shinkai-message-ts: Handles message protocols and network communication with Shinkai Node.
    • shinkai-node-state: Manages node data using React Query.
    • shinkai-ui: A reusable React component library.
    • shinkai-artifacts: UI primitives built on Radix and Tailwind CSS.
    • shinkai-i18n: Internationalization utilities.

    Technology Stack:

    • Frontend: React 18, TypeScript, Tailwind CSS, Radix UI
    • Desktop: Tauri (Rust + React)
    • State Management: Zustand (UI state) and React Query (server state)
    • Build System: Vite, NX monorepo

  8. Understand the Shinkai Desktop update distribution flow

    main

    Shinkai Desktop uses the Tauri updater flow to deliver updates via a Cloudflare R2 bucket.

    1. Artifact Storage

    Artifacts are uploaded to R2 using the following path structure: shinkai-desktop/binaries/[development|production]/{arch}/{version}/*

    Example: shinkai-desktop/binaries/development/aarch64-apple-darwin/0.5.5/*

    2. Update Discovery

    When the app starts, it fetches a JSON file from: shinkai-desktop/binaries/[development|production]/updates.json

    This file tells the app if a new version is available for the current platform and provides the download URL and signature.

    3. Update Lifecycle

    1. App Start: Fetches updates.json.
    2. Version Check: Compares local version with the version in the JSON.
    3. Signature Verification: Verifies the JSON signature.
    4. Download: If a valid update is found, downloads the artifact specified in the url field.
    5. Installation: Installs and restarts the app.

  9. Manage WebSocket subscriptions and topics

    main

    The streaming architecture uses a shared WebSocket connection (configured with { share: true }) to optimize resources. Subscriptions are managed via topics:

    • Topic: inbox
    • Subtopic: The specific inboxId

    Messages are automatically filtered by the inboxId in the handler. Subscriptions persist when switching inboxes and are cleaned up automatically when the component unmounts.

  10. How Shinkai architecture is organized

    main

    Shinkai is built as an NX Monorepo. The architecture is split into a core application and several shared libraries:

    Core Application

    • shinkai-desktop: A cross-platform Tauri application using a React frontend.

    Shared Libraries

    • shinkai-message-ts: Messaging protocol and network communication with Shinkai nodes.
    • shinkai-node-state: Reactive state management for node data using a query-based approach.
    • shinkai-ui: A reusable component library with a design system.
    • shinkai-artifacts: Styled UI primitives built on Radix and Tailwind CSS.
    • shinkai-i18n: Internationalization utilities powered by i18Next.

    Technology Stack

    • Frontend: React 18, TypeScript, Tailwind CSS, Radix UI
    • Desktop: Tauri (Rust + React)
    • State Management: Zustand (UI State) and React Query (Server State)
    • Build System: Vite, NX Monorepo
    • Testing: Vitest, React Testing Library

  11. Manage Shinkai Desktop versioning

    main

    To simplify versioning in the monorepo, Shinkai Desktop uses the package.version attribute from the root package.json. You do not need to manually update tauri.conf.json or src-tauri/cargo.toml for new releases.

    Development Versioning Pattern

    For development builds, the versioning follows the pattern: {package-version}.{ci-build-number}.

    Important: Because the package-version remains static across multiple development builds, the ci-build-number is appended without a dot (e.g., 0.5.5123 instead of 0.5.5.123). This is because Tauri and current app bundlers do not support the semver pre-release/build metadata format in a way that is compatible with the current updates.json logic. Changing this format will break the update system.

  12. Understand the Frontend Streaming Architecture

    main

    The Shinkai frontend uses a hybrid approach to handle real-time AI chat responses. This architecture separates ephemeral streaming state from persistent data to ensure high performance and smooth UI updates.

    Core Components:

    • WebSocket: Delivers real-time tokens from the backend.
    • Zustand Store: Manages ephemeral streaming state (e.g., tokens currently being typed). This avoids the performance cost of updating the persistent React Query cache 20+ times per second.
    • React Query: Manages persistent, finalized message data and caching.

    Data Flow Summary:

    1. Optimistic Update: When a user sends a message, the UI immediately inserts 'optimistic' user and assistant messages into the React Query cache.
    2. WebSocket Streaming: Tokens arrive via WebSocket, are buffered, and then flushed to the Zustand store at ~20 FPS.
    3. Finalization: Once streaming is complete, the final message data is saved to React Query, and the ephemeral Zustand state is cleared.