Shinkai Apps

Shinkai is a two-click install AI manager (local and remote) that lets you spin up AI agents in minutes through a friendly UI. Agents and tools are all exposed via an MCP server.

A companion repository, Shinkai Node, provides the core services for agent management, job processing and secure communications.

Key Features

• Rapid Agent Setup – create and configure agents in under five minutes with a guided UI.
• Local or Remote – run everything on your machine or connect to a remote Shinkai Node.
• MCP Server Integration – expose agents and tools over an MCP server for easy automation.

Demo

shinkai-demo.mp4

Documentation

General Documentation: https://docs.shinkai.com

Repository Structure

Apps

• shinkai-desktop – cross-platform desktop UI (can also run in the browser).

Libs

• shinkai-message-ts – message definitions and network helpers for talking to Shinkai Node.
• shinkai-node-state – React Query based state management for node data.
• shinkai-ui – reusable React components used across the apps.
• shinkai-artifacts – styled UI primitives built on top of Radix and Tailwind.
• shinkai-i18n – translation utilities powered by i18next.

Getting started

To get started first clone this repo:

$ git clone https://github.com/dcSpark/shinkai-apps

Download side binaries:

Macos

ARCH="aarch64-apple-darwin" \
OLLAMA_VERSION="v0.6.8" \
SHINKAI_NODE_VERSION="v1.0.4" \
npx ts-node ./ci-scripts/download-side-binaries.ts

Linux

ARCH="x86_64-unknown-linux-gnu" \
OLLAMA_VERSION="v0.6.8" \
SHINKAI_NODE_VERSION="v1.0.4" \
npx ts-node ./ci-scripts/download-side-binaries.ts

Windows

$ENV:OLLAMA_VERSION="v0.6.8";
$ENV:SHINKAI_NODE_VERSION="v1.0.4";
$ENV:ARCH="x86_64-pc-windows-msvc";
npx ts-node ./ci-scripts/download-side-binaries.ts

Run one of the projects

Once you have done that simply use npm to compile/serve it yourself:

cd shinkai-apps
nvm use
npm ci
npx nx serve {project-name} # IE: npx nx serve shinkai-desktop

Project specific configurations

• shinkai-desktop – for development and building purposes
  • Run as a Desktop App using Vite: Run npx nx serve:tauri shinkai-desktop and it will automatically launch the Shinkai Desktop application.
  • Run as a Web App: Run npx nx serve shinkai-desktop and open a browser and navigate to http://localhost:1420.

Useful Commands

Every command, if it's needed, build projects and it's dependencies according to the project dependency tree inferred from imports between them.

• Run a single task

  Command: npx nx [target] [project-name]

  Params:

  • target: build | serve | lint | test | e2e

  IE:

  • npx nx build shinkai-desktop
  • npx nx lint shinkai-message-ts
  • npx nx test shinkai-ui
  • npx nx serve shinkai-desktop

• Run many tasks

  Command: npx nx run-many --target=[target]

  Params:

  • target: build | serve | lint | test | e2e

  IE:

  • npx nx run-many --target=build
  • npx nx run-many --target=lint
  • npx nx run-many --target=test
  • npx nx run-many --target=e2e
  • npx nx run-many --target=serve

• Run on affected projects

  Command: npx nx affected --target=[target]

  Params:

  • target: build | serve | lint | test | e2e

  IE:

  • npx nx affected --target=build

When you build a project, NX builds a cache (to make it faster), if you want to skip it just add the parameter --skip-nx-cache to the previous commands.

• Create a dev build

  • NODE_OPTIONS="--max_old_space_size=8192" npx nx build shinkai-desktop --config="./src-tauri/tauri.conf.development.json"

• Update ollama models repository

  • npx ts-node ./ci-scripts/generate-ollama-models-repository.ts

Dev conventions

Monorepo

To orchestrate all the tasks, dependencies and hierarchy between different projects, this repository uses NX as a monorepo tooling.

Third party dependencies

All projects share the same base of dependencies defined ./package.json file found in the root of the repository. Nested package json files are used just to override or extends base attributes.

UI Libraries

To build the UI there are 3 core libraries:

• radix to have base unstyled components.
• shadcn to obtain ready to use components.
• tailwindcss to implement css customizations, structures, layouts and helpers.

State management

To implement state management there are two different libraries:

• zustand: To implement UI State
• react-query: To implement data state