OpenNeko Docs

Install OpenNeko, connect governed data sources, run agent work, and extend the system with skills and plugins.

What OpenNeko is

OpenNeko is an operator-first agent workspace. It gives teams a local control plane for AI work: users talk to an agent, the agent reads approved business context, proposes or executes governed actions, and the system keeps auditable records of the work.

A normal deployment includes the web app, worker, metadata Postgres database, GraphJin metadata API, and OpenShell sandbox runtime. The app is where operators review threads and approvals. The worker runs queues, workflows, plugins, memory extraction, watcher sweeps, and sandboxed agent jobs.

The operating model follows OUDA: observe the request and source context, understand the relevant facts, decide on a response or action, then act through the trusted control plane. The agent loop is sandboxed; approvals, audit, secrets, and durable writes stay in OpenNeko.

Threads collect human requests, agent runs, cards, memory proposals, action requests, and workflow outputs.
GraphJin exposes metadata and, in demo or connected deployments, governed customer-data GraphQL endpoints.
OpenShell isolates agent execution and plugin work behind default-deny egress policies.
Plugins add connectors, actions, SSO providers, and channel integrations without moving secrets into the browser.

Default path

Install the OpenNeko CLI with the bootstrap installer or a platform package.
Run the setup wizard and pick demo, production, or development mode.
Connect a data source or start with the AdventureWorks demo database.
Invite operators, configure action policies, and install any plugins you need.
Use threads and workflows to turn repeated operational work into governed agent runs.

System map

Layer	Primary responsibility	Where it runs
Web	Threads, approvals, integrations, signin, admin UI, and operator review	Next.js app container
Worker	Agent runs, workflows, plugins, memory, behavior alarms, and queues	Node worker container
Metadata database	Org state, threads, runs, policies, memory, audit rows, plugins, and workflow records	Postgres with pgvector
GraphJin	GraphQL access to metadata and governed customer data	Metadata service plus optional source services
OpenShell	Sandboxed execution, mTLS gateway, network policy, and model egress proxying	Gateway plus per-run boxes

Docs map

Start

Overview
Install OpenNeko, connect governed data sources, run agent work, and extend the system with skills and plugins.
Quickstart
Install the CLI, create a demo stack, and reach the web app in a few commands.
Install and Upgrade
Choose an install method, run setup, manage ports, and replace the CLI safely.
Connect Data
Expose approved databases through GraphJin and keep source access governed by roles and policies.

Build

Core Concepts
Understand the entities that make up OpenNeko's control plane.
Operating Loop
See how a user request moves through the agent, control plane, sandbox, and approvals.
Workflows and Watchers
Define repeatable agent work with cron triggers, data-change triggers, and metric watchers.
Actions and Approvals
Route privileged operations through action policies, approval states, and execution records.
Memory and Context
Manage durable team knowledge, personal layers, pending memories, and integrity checks.
Skills
Install, package, and create agent skills that load at turn time.

Govern

Rules and Governance
Use policy rows, feature gates, audit events, and behavior alarms to keep agent work reviewable.
Security
Understand the sandbox, model key handling, SSO boundary, and behavior alarm controls.
Audit
Track control-plane operations and, when enabled, export a hash-chained audit log.

Extend

Plugins
Install marketplace plugins and understand action, auth, connect, and channel capabilities.
SSO and Signin
Configure plugin-backed signin and understand the singleton SSO provider model.
Connected Accounts
Use connect capabilities for per-operator OAuth and external service credentials.

Operate

CLI Reference
Run setup, manage services, install plugins and skills, inspect logs, and reset local state.
Contributing
Work on OpenNeko locally and keep docs, plugins, skills, and tests aligned.
Licensing and Editions
Understand open-source behavior, feature flags, and licensed controls.