# Neuralis documentation

> Machine-readable access — this index lists every page; below are the bulk endpoints an agent should prefer:

- Full corpus (one file): /llms-full.txt
- Per-section corpus: /llms-full/<section>.txt — sections: admin, agent-core, brain-core, enterprise, getting-started, machine-core, package-system, use-cases
- Any page as raw markdown: append `/content.md` to its slug under `/llms.mdx/docs` (e.g. /docs/agent-core/tools → /llms.mdx/docs/agent-core/tools/content.md)

---
# Documentation

- [What is Neuralis](/docs): A self-hosted platform that runs AI agents like a workforce — built on one universal package protocol and one shared brain.
- Getting started
  - [Getting started](/docs/getting-started): Install Neuralis, complete first-run setup, and learn the core concepts.
  - [Installation](/docs/getting-started/installation): How Neuralis is distributed and how to run it.
  - [Maturity](/docs/getting-started/maturity): How far each part of Neuralis is today — what the maturity labels mean and how a score is formed.
  - [First-run setup](/docs/getting-started/first-run): Owner account, boot configuration, and connecting your first model provider.
  - [Core concepts](/docs/getting-started/core-concepts): Projects, agents, packages, skills, contributions, roles, features, sources, and sessions.
  - [The workspace](/docs/getting-started/workspace): A tour of the Neuralis workspace: chat, calendar, files, terminal, machine, and admin.
- Use cases
  - [Use cases](/docs/use-cases): What an AI workforce actually does all day — seven playbooks for real work, from a one-person company to a software team.
  - [The solo operator](/docs/use-cases/solo-operator): A one-person company with a staff of agents: research, content, follow-ups, and back office.
  - [The marketing team](/docs/use-cases/marketing-team): A full online presence run as a department: strategist, content creator, follow-up agent, analyst.
  - [The content studio](/docs/use-cases/content-studio): An AI persona with a real identity, a content pipeline, and a publishing calendar.
  - [Commerce operations](/docs/use-cases/commerce-ops): Product research, listings, customer support drafts, and order follow-up for an online store.
  - [The research desk](/docs/use-cases/research-desk): A market-analysis desk — live data over MCP, scheduled briefings, durable notes, human judgment.
  - [The software team](/docs/use-cases/software-team): Planner, coder, and reviewer agents working a real repository — with a desktop and a terminal.
  - [Connect anything](/docs/use-cases/connect-anything): The capability pool: MCP servers, imported skills, public APIs, and your own packages — four on-ramps to one contract.
- @package-system
  - [The package system](/docs/package-system): Every capability in Neuralis is a package — the protocol that makes that work.
  - [First-party packages](/docs/package-system/first-party-packages): The first-party packages that ship with Neuralis installations, and what builtin-class means.

  - **Contract**
  - [Directory contract and discovery](/docs/package-system/directory-contract): The shape of a Neuralis package and exactly what file-first discovery scans.
  - [Manifest and distribution](/docs/package-system/manifest): The neuralis block in package.json: identity, trust, features, surfaces, and packaging.
  - [Tools](/docs/package-system/tools): Schema-first tool definitions: strict JSON Schema, the x-neuralis extension, and result bounding.
  - [Instructions, rules, agents, docs, and team](/docs/package-system/contributions): The markdown contribution categories and how each reaches the system prompt.
  - [Sessions and identity](/docs/package-system/sessions): The canonical session context, the per-stream session ticket, and identity boundaries.
  - [Connectors](/docs/package-system/connectors): The connector port: filesystem-like sources with declared capabilities and closed config schemas.

  - **Access & policy**
  - [Features and access](/docs/package-system/features-and-access): Feature grants, role defaults, and the deny-by-default visibility predicate.
  - [URI policies](/docs/package-system/uri-policies): Path protection for package namespaces, declared in the manifest and enforced at four layers: route, UI, tool, and vector index.

  - **Runtime**
  - [Lifecycle and trust tiers](/docs/package-system/lifecycle): How packages execute: in-process, WASM sandbox, or MCP — and what each trust tier may do.
  - [Routes](/docs/package-system/routes): Declaring HTTP route handlers with patterns and feature gates.
  - [Runtime stack and substitution tokens](/docs/package-system/runtime-stack): What packages and skills can know about where they run, and the tokens resolved at activation.
  - [App surfaces](/docs/package-system/app-surfaces): Widgets, cards, and docks — the renderer and trust matrix for package UI.
  - [Skill launcher](/docs/package-system/skill-button): One reusable affordance any package drops into its UI to hand a skill to the agent — it prefills the chat composer exactly like a slash pick, never sends, and derives its own visibility so it can never advertise a skill the caller cannot run.

  - **Authoring & build**
  - [Create a package — all three ways](/docs/package-system/create-a-package): The three ways to ship a Neuralis package (installed node, project WASM, source markdown) — one PackageDefinition, side by side.
  - [Building your own first-party package](/docs/package-system/external-first-party): How to develop a first-party Neuralis package that lives in its own repository — the two trust lanes, the build contract, kernel peers, and the four separate acts between git and a loaded package.
  - [Skills](/docs/package-system/skills): The full skill protocol: agentskills.io-aligned SKILL.md, Neuralis frontmatter extensions, activation, and scripts.
  - [Source packages](/docs/package-system/source-packages): How synced filesystem sources contribute markdown packages — recognized layouts, defaults, per-file control, and the security model.
  - [Testing and validation](/docs/package-system/testing): Validation rules applied at load time and the test helpers packages can use.
  - [Building for WASM](/docs/package-system/wasm-build): The build pipeline for sandboxed project packages.
  - [The contract examples](/docs/package-system/reference-package): Three official example packages — one per install class — published to the package registry as the canonical, machine-readable package contract.

  - **Distribution**
  - [The neuralweb marketplace](/docs/package-system/marketplace): The package protocol's distribution surface — publish, vet, audit, and install AI capabilities down to a single element.
- @agent-core
  - [agent-core](/docs/agent-core): The agent runtime: conversations, streams, model providers, tools, MCP, and the chat UI.
  - [API & usage](/docs/agent-core/api-usage): How to CALL agent-core: the model-facing tools, the feature-gated HTTP route surface, and the typed getPackageApi() consumer surface.
  - [Tools](/docs/agent-core/tools): The native tools agent-core gives every agent: execute, delegate, web tools, workflows, and the bounded connection control plane.
  - [Skills](/docs/agent-core/skills): The first-party SKILL.md bundles agent-core ships: management, execution patterns, research, and inspection.
  - [Workflows](/docs/agent-core/workflows): Scheduled and queued agent work: workflow entries, triggers, the run queue, and creator identity.
  - [Agents](/docs/agent-core/agents): The seven base subagents under agents/, and how delegate spawns agent runtimes with their own loop.
  - [Instructions and rules](/docs/agent-core/instructions-and-rules): The always-on system-prompt contributions under instructions/ and rules/: the kernel, working memory, and tool-use floor — plus the durable agent-memory model.
  - [Connectors](/docs/agent-core/connectors): The connector lifecycle agent-core owns: OpenAPI and remote MCP connectors, configure, connect, and reconnect.
  - [Channels](/docs/agent-core/channels): Connect Telegram and WhatsApp to your workflows: per-user connections, pairing, bindings, and result delivery.
  - [Git remotes](/docs/agent-core/git-remotes): Connect a git remote so agents can push and pull: one-click OAuth on GitHub, GitLab, Bitbucket and Codeberg, per-user push tokens, and the OAuth App credential.
  - [Bring your own keys](/docs/agent-core/bring-your-own-keys): Set your own API keys and secrets from the chat config panel — self-service, user-scoped BYOK, no admin required.
  - [Providers and models](/docs/agent-core/providers-and-models): The multi-provider model layer: the declarative catalog, thinking controls, custom endpoints, and credential scoping.
  - [App surfaces](/docs/agent-core/app): The workspace widgets agent-core contributes: the Chat widget, the Calendar widget, and the Terminal widget.
  - [Terminal](/docs/agent-core/terminal): The PTY terminal widget: managed sessions, source-scoped tabs, supervision, and container/host execution planes.
  - [Security](/docs/agent-core/security): agent-core's security posture: the shell sandbox, URI-policy gating, env sanitization, data isolation, and the MCP boundary.
- @admin
  - [admin](/docs/admin): The admin dashboard: users, projects, roles, config, credentials, and audit.
  - [API and usage](/docs/admin/api-usage): How admin exposes its capabilities — feature-gated HTTP routes and the one typed agent-core adapter — without shipping any tools or commands.
  - [Features and routes](/docs/admin/features-and-routes): The two-tier project.* / platform.* feature namespace and the backend surface it gates.
  - [App surfaces](/docs/admin/app): The admin dashboard widget: PROJECT/PLATFORM sidebar, panels, and deep-link state.
  - [Skills](/docs/admin/skills): Six management skill bundles that let an agent operate the platform.
  - [Workflows](/docs/admin/workflows): The System maintenance workflow template admin ships: a daily platform-health pass for owners and admins that reports everything and remediates only within a narrow closed list.
  - [Security](/docs/admin/security): Admin security invariants: server-side gates, credential tiers, and audit recording.
- @brain-core
  - [brain-core](/docs/brain-core): The URI-native filesystem, scoped sources, and vector memory.
  - [API usage](/docs/brain-core/api-usage): The brain-core public surface agents and packages consume: the four fs_* tools, the source and URI-policy HTTP routes with their feature gates, and the typed package API other packages call.
  - [Tools](/docs/brain-core/tools): The four fs_* tools brain-core contributes: read, list, search, and write across the URI-native filesystem.
  - [Sources and connectors](/docs/brain-core/sources-and-connectors): Source kinds, the URI vocabulary, and how files resolve across environments.
  - [Memory and sync](/docs/brain-core/memory-and-sync): Vector memory, embedding, and the sync pipeline.
  - [Skills](/docs/brain-core/skills): File, source, and policy management skills — plus the one package-authoring skill.
  - [Files UI](/docs/brain-core/files-ui): The Files workspace surface: browsing and searching sources, the editor and diff views, Git Control, pending-change review, and source administration.
- @machine-core
  - [machine-core](/docs/machine-core): The sandboxed desktop machine: browser automation, desktop control, and capture.
  - [API & usage](/docs/machine-core/api-usage): machine_use, URI-routed execute, the HTTP route surface and its feature gates, the webtop source connector, and the typed cross-package API.
  - [Tools](/docs/machine-core/tools): Browser and desktop automation through machine_use, and Webtop shell through agent-core’s execute.
  - [The machine_use tool](/docs/machine-core/machine-use): The unified action surface for browser and desktop automation.
  - [Machine sources](/docs/machine-core/sources): The machine filesystem source and how agents exchange files with the sandbox.
  - [Deployment](/docs/machine-core/deployment): Container requirements, runtime configuration, and operational notes.
  - [Skills](/docs/machine-core/skills): Machine session management and driving guidance.
- Enterprise
  - [Enterprise](/docs/enterprise): Deploying and governing Neuralis — and the AI workforce inside it — for an organization.
  - [Deployment](/docs/enterprise/deployment): The Docker stack, runtime topology, persistence, and health checks.
  - [Configuration](/docs/enterprise/configuration): Boot configuration, platform settings, and model providers.
  - [Multi-tenancy](/docs/enterprise/multi-tenancy): Projects, membership, and isolation guarantees.
  - [Security model](/docs/enterprise/security-model): The six security layers every request passes through, deny-by-default.
  - [Roles and features](/docs/enterprise/roles-and-features): Built-in and custom roles, feature grants, and priority-gated assignment.
  - [Credentials](/docs/enterprise/credentials): The encrypted credential store and its four scopes.
  - [Administration and audit](/docs/enterprise/administration): Operating a Neuralis instance day to day.
  - [External MCP access](/docs/enterprise/mcp-access): Connecting external MCP clients: authentication and the exposed surface.
  - [Licensing](/docs/enterprise/licensing): The FSL-1.1-ALv2 / Apache-2.0 split, what you may build and sell, and the two-year Apache conversion.