Start here
Select the guide for your role. The user guide tells you how to work in a session. The admin guide tells you how to set up models, skills, connections, rules, and people.
Documentation baseline. This guide follows public Core main, checked on November 14, 2026 against commit 31ee4eb. Operators and contributors can use the Core documentation index for setup, deployment, and implementation details.
I'm a regular user
I want to ask questions, give tasks to the agent, and work with files.
Go to User Guide →I'm an admin or developer
I set up the platform, release skills, connect data sources, and manage access.
Go to Admin Guide →What is Cogniplane?
Cogniplane is a governed AI workspace for organizations. Each person works in sessions. Admins release organization skills and connections. Members can release private skills for their own chats, and project managers can release project skills. The session's scope, capability selection, and organization policy determine what the agent can use. Admins can review sessions, tool calls, and approval decisions.
Governed skills and connections
Admins review skills and MCP connections before release. They release each one to test users or to all members.
Approvals in the chat
Actions that need approval stop and wait. The person who started the turn approves or declines. The runtime enforces the approval settings, not the prompt.
Organization isolation
PostgreSQL row-level security scopes each tenant query to one organization. Shell commands run in a per-session sandbox.
Audit trail
Admins can replay a session conversation and read its tool calls, approvals, privacy scans, and audit events. A change history records admin changes.
How it works at a glance
A user sends a message. The agent reads the descriptions of the skills available in the session, opens the skill that matches the request, and calls the tools it needs. The response and tool activity stream into the conversation. The agent runs in the backend. Connector, proxy MCP, and Cogniplane built-in tools use the MCP gateway, which adds credentials and applies Policies rules. Built-in tools include session files, project files, and memory. Sandbox shell and file commands use a separate path with runtime approval and network controls. Model calls go directly from the backend to the selected provider.
Who uses this documentation
CTOs and Heads of AI evaluating the platform
Read Platform Overview, Agent Behavior & Policies, Privacy, and Deployment for the architecture, the governance model, and the security posture.
Engineers doing the implementation
The admin guide tells you how to add model providers, connect MCP servers, write and release skills, set approvals and rules, configure PII protection, and manage people.
CISOs and security reviewers
The admin sections cover row-level security, local accounts and WorkOS sign-in, roles, identity confirmation for sensitive changes, credential handling, Policies, and session review.
Business users starting in the workspace
The user guide covers sessions, models, skills, approvals, files, projects, and scheduled jobs.
Platform capabilities at a glance
Choice of model provider
Anthropic, OpenAI, Google, OpenRouter, and Z.AI. An owner saves the API keys. Admins choose which models members can use. Members select a model, and a reasoning effort when admins show it.
PII protection
Off by default. Detect, Block, or Transform. Transform masks values in chat prompts only. Uploads and imports are detected or blocked.
Skills library and marketplace
Add skills from a marketplace, GitHub, a ZIP file, or pasted SKILL.md text. Each import waits for review before release. Members can submit private skills for review.
Staged release to test users
Release a skill or an MCP connection to test users first. Release it to all members after you check it.
Built-in integrations
Notion, GitHub, Jira, and Microsoft 365 with SharePoint and OneDrive are included in Core. Jira is read-only. Each user connects a personal account for use in standalone chats. Operators configure the connectors before admins enable them.
Policies
Ordered rules for MCP gateway tool calls: Allow, Require actor confirmation, or Block. Run them in Monitor mode first, then in Enforce mode.
Projects and scheduled jobs
Share sessions and files in a project with owner, editor, and viewer roles. Run a prompt on a daily, weekly, or cron schedule.
Usage and model budget
Token reports by user and model, with estimated cost. An optional monthly model budget stops new turns when the limit has no room.
Getting Started
Cogniplane runs in your browser. Your admin gives you the link to your organization's Cogniplane instance.
Signing in
The sign-in page shows the methods enabled for your deployment:
- Local account. Open the setup link sent by your administrator or by email and set your password. Then sign in with your email and password. Complete any required authenticator or passkey step.
- Sign in with a passkey. When passkeys are enabled and you have registered one, select this option and follow your browser's prompt.
- WorkOS sign-in. Use the hosted email sign-in or Sign in with SSO. For SSO, enter your Organization ID or slug. Your organization controls access through its identity provider.
For a local password reset, select Forgot your password? when it is available. If email recovery is not configured, ask your administrator for a reset link. Local account settings are under Settings > Sign-in & security.
The main screen
- Sidebar (left). Search sessions, the New session button, your projects, and your sessions. The bottom of the sidebar has links to Projects, Archived sessions, and Settings.
- Header (top). The session title, the Session capabilities button, the session actions menu, and the workspace menu. The workspace menu opens Artifacts, Settings, Admin, and Keyboard shortcuts.
- Chat area (center). The model picker and the context meter are at the top. Approval controls normally appear in the tool card that needs a decision. The message box is at the bottom.
- Artifacts panel (right). Two tabs: Context (files you add) and Artifacts (files in the session). Use the panel button in the header to show or hide it.
- Side panel. Generated forms, checklists, and other views have their own panel. See Generated views.
The context meter shows how full the model context window is and the estimated cost of the session.
Settings
Open Settings from the sidebar or the workspace menu. The pages are:
- Connected accounts. Connect your accounts for the services your organization enabled, for example GitHub, Notion, Jira, or an MCP connection that needs your own credential.
- Skills & connections. Set your default skills and connections for your chats. Write private skills and submit them for review.
- Skill updates. Read the review decisions for skills you submitted.
- Memories. Review, edit, or delete the facts the agent saved with your approval.
- Sign-in & security. For local accounts, manage your password, authenticator, passkeys when enabled, and recovery codes. You can also sign out of all devices.
- Token usage. See your token use and estimated cost across sessions.
- Scheduled jobs. Create and manage recurring prompts. See Scheduled Jobs.
Starting your first conversation
-
Click New session
Select Personal session or a project, then click Create session. A personal session is private to you.
-
Type your question or task
Write as you would to a colleague. Ask a question ("What were our top 5 products last quarter?") or give a task ("Summarize this PDF and list the action items").
-
Watch the agent work
Tool calls appear in the conversation. When an action needs your approval, an approval card appears. See Tool Actions & Approvals.
-
Continue the conversation
The agent keeps the full conversation of the session. Ask follow-up questions, correct the agent, or change the task.
Having a Conversation
Talk to the agent as you would brief a colleague. The agent can use your organization's connected systems, so you can ask it to check the data.
What to ask
Questions
"What does the Q3 policy document say about travel expenses?"
Tasks
"Summarize the contract in Context and flag unusual clauses." or "Pull the monthly sales figures and write a short briefing."
Tips for better results
- Say what result you want. "Give me a 3-bullet summary" gives a more focused answer than "tell me about this."
- Name the data source if you know it. "Check the HR policy pages in Notion" helps the agent select the correct tool.
- Correct the agent. If the answer is wrong, say so. The agent tries again.
- Give multi-step tasks in one message. The agent can do compound tasks.
Choosing a model and reasoning effort
Click the model picker at the top of the chat. Search or select a model from the list. The list shows only the models that your admins made available, grouped by provider. You cannot change the model while the agent works.
If your admins show the reasoning effort, the picker also has Reasoning effort. Higher effort lets the model think longer before it answers. This costs more and takes more time. The control shows only for models that accept more than one effort level.
Stopping the agent
To stop the agent while it works, press Esc or click the stop control. The server ends the turn. This also stops a turn that you started in a different browser tab.
Understanding the response
- Tool cards. Each tool call shows the tool name and its status (running… or done). Click the card to see the input sent to the tool and the result.
- Plan and reasoning. When the model gives a plan or reasoning text, it appears in the conversation.
- The answer. The response that uses the data from the tools.
- Interactive tool views. Some MCP tools return an interactive view. Cogniplane shows it in the conversation in an isolated frame.
Generated views
The agent can create forms, checklists, and other views while it works. Open Side panel or use View side panel in the conversation. This panel is separate from Context and Artifacts. Use Switch view to return to an earlier view; check its status before you use it.
Changing a control does not send a message. Review the changed values beside the message box before you send your next message. Use in reply adds the selected output to your draft. Review and send that draft when it is ready.
Memory
When your organization enables memory tools, the agent can propose short facts and preferences for later standalone chats. Before it saves or replaces a memory, you must approve the exact text. An approval for one memory does not approve later saves.
Open Settings > Memories to review, edit, or delete saved facts. Project chats do not use personal memories. See What changes in a project chat.
When the agent cannot help
- The data source is not connected, or it is not released to you. Ask your admin.
- In a standalone chat, you did not connect your account for the service. Go to Settings > Connected accounts. Project chats exclude personal connections even when your account is connected.
- The session capabilities exclude the skill or connection. See Using Skills.
- A Policies rule or a PII setting blocked the action. The message tells you the reason when one is available.
If the organization or user running-turn limit is reached, your message is not sent or queued. Wait for an agent to finish, or stop one, then send your message again.
Back to contents ↑Using Skills
A skill gives the agent instructions for one type of work. Examples are a Sales Intelligence skill, an HR Policy Advisor skill, or a Contract Analyst skill.
How the agent uses skills
You do not select a skill in the chat. The agent gets the name and description of each skill that is available in the session. When your request matches a description, the agent opens that skill and follows its instructions.
A standalone chat can use released organization and private skills. A project chat can use released organization and project skills. Your admin decides which organization skills you can use. Projects and scheduled jobs do not use your private skills.
Limiting skills and connections for a session
-
Click Session capabilities in the header
The dialog lists the skills and connectors for the session.
-
Select Choose for this session
Clear the skills and connectors that you do not want. Organization policy always applies.
-
Click Save capabilities
The change applies to the next turn.
To set defaults for all your standalone chats, go to Settings > Skills & connections. Projects and scheduled jobs use their own settings.
Private skills
You can write private skills for your own standalone chats. Only you can use them. Projects and scheduled jobs do not use them.
-
Go to Settings > Skills & connections
Under Private skills, click Create skill.
-
Write the draft and review it
Save the draft, read its instructions and validation results, and select the review checkbox. Click Make revision N available, where N is the saved revision. A draft is not available to the agent until you release it.
-
Optional: submit it to your organization
Click My submissions, then New submission. Select a saved revision, add a note to reviewers, and click Submit for review. Your private skill stays yours. Read the decision in Settings > Skill updates.
If a chat uses a saved capability selection, add the newly released skill in Session capabilities. Releasing a skill does not add it to an existing selection. To share a skill in one project, see Project skills.
Back to contents ↑Tool Actions & Approvals
The agent uses tools to do work: it reads files, calls connected services, and, when allowed, runs shell commands.
Read-only actions
Read-only tools run without a prompt when your organization enables Auto-approve read-only tools. This is the default. In a project with Manual approval, the agent asks before approval-governed actions, including read-only tools.
Actions that need approval
When an action needs approval, execution pauses. Look for needs approval in the relevant tool card and review its decision controls. If there is no visible linked tool card, Cogniplane shows the request in the separate notification list. Requests can cover:
- Shell command. A command in the sandbox. Only when the owner allows command execution.
- File change. A change to a file in the agent workspace.
- Tool call. A call to a connection or integration tool, for example a write to Notion.
- Permission request. A request for more access.
The card also shows a summary of the action input. Click a long summary to see all of it.
Your choices
| Button | Result |
|---|---|
| Decline | The action does not run. The agent continues and can try a different approach. |
| Approve once | This action runs. The next action of the same type asks again. |
| Allow for this turn | When offered, this action and later calls to the same tool in the same turn run without another native approval prompt. Policies can still require approval for each call. Exact-value saves, including memory saves, do not offer this choice. |
Viewing tool activity
Each tool call has a card in the conversation. Click the card to see:
- The tool name
- The input sent to the tool
- The result from the tool
Working with Files
Add a file to a session when you want the agent to work with it, for example a contract, a report, or a data extract.
How to add a file
-
Open the artifacts panel
Click the panel button in the header, or press the shortcut. Select the Context tab.
-
Click Add source
Select Upload from this device and pick a file. If your organization connected a file source, you can select it here and import a file from it.
-
Ask your question
Files in Context are given to the agent on every turn until you remove them. Only you can add or remove them.
Supported file types
| Type | Formats |
|---|---|
| Text and data | Plain text, Markdown, CSV, JSON, HTML |
| Code | Python, TypeScript, JavaScript, shell scripts |
| Documents | PDF, Word (.docx), Excel (.xlsx) |
| Images | PNG, JPEG, GIF, WebP |
The default upload limit is 25 MB per file. Cogniplane checks the declared file type against the file content.
How the agent reads files
- When a selected file is copied into the agent workspace, the agent receives its path and can read the full file there.
- If copying is unavailable or fails, Cogniplane supplies a text or PDF excerpt when it can extract one. The excerpt can be shorter than the full file.
- Working with full Word and Excel files requires the sandbox tools. The owner must enable command execution.
Importing from Microsoft 365
Microsoft 365 is included in Core and Cloud. Once the operator configures it and your organization enables reads, connect your Microsoft account. Use Add source to browse SharePoint and OneDrive and import a file into a session where you can upload. The Microsoft import scope controls its PII scan. In a project chat, the agent cannot use your personal Microsoft connection itself. Files you explicitly import into that chat are shared with project members.
Files stay in the session
An uploaded file belongs to the current session. You can refer to it many times in the session. The agent can also list and read other files in the session. Files in a project session are visible to the members of the project.
Back to contents ↑Artifacts & Previews
When the agent creates a file, for example a report or a script, Cogniplane saves it in the session as an artifact. The Artifacts tab of the artifacts panel lists all files in the session.
Preview
Click Preview on an artifact. These formats have a preview:
- Markdown. Shown as formatted text.
- Text, code, CSV, and JSON. Shown as text with syntax highlighting.
- HTML. Shown in an isolated frame. Scripts do not run.
- Images. PNG, JPEG, GIF, and WebP.
- PDF. Shown as extracted text.
- Word and Excel. No preview. Download the file.
Downloading artifacts
Click Download. Each download link works one time and expires after 15 minutes (default). If you paste the link somewhere, it does not give access to the file again.
Using artifacts in the conversation
Select the checkbox on an artifact to add it to Context. The agent then gets the file on every turn.
All your files
To see files from all your sessions, open the workspace menu and select Artifacts. You can search, preview, and download files there.
Back to contents ↑Managing Sessions
Each conversation is a session. A session keeps its own history, files, and settings.
Your session list
The sidebar groups your sessions: Needs attention (for example a pending approval), Pinned, Today, and Earlier. Project sessions show under their project. Click a session to open it. The full history is kept.
To find a session, type in Search sessions. The search matches session titles.
Session actions
Open the session actions menu (⋯) in the header. The menu has:
- Rename session. You can also click the title in the header.
- Pin session or Unpin session. Pinned sessions stay at the top.
- Copy session link. Copies a link to the session.
- Add to project. Moves the session into a project. All people with access to the project can then see its history and files. You cannot undo this in the current release.
- Archive session. Removes the session from the sidebar. You cannot archive while the agent works or while an approval is pending.
- Delete session. Moves the session and its local files to Trash. Trash keeps them for 30 days (default).
The header also has Copy session to clipboard, which copies the conversation as text.
Archived sessions
Click Archived sessions at the bottom of the sidebar. Use Search archived sessions to find one. Click Restore to put it back in the sidebar, or use the delete button to move it to Trash.
Projects
A project keeps related sessions, reference files, and instructions in one place. You can share a project with other people in your organization.
What changes in a project chat
Project members can read shared replies and tool results. Project chats therefore exclude your saved memories, private chat history, personal GitHub, Notion, Jira, and Microsoft accounts, and MCP connections that require each member's credential. Connecting or reconnecting your account does not remove this restriction.
Project chats can use organization MCP connections, permitted built-in tools, and released organization and project skills. Moving a standalone chat into a project can remove capabilities it used before. Review its files and conversation before sharing it.
Creating a project
-
Click Projects in the sidebar
Type a name and click Create project.
-
Add sessions and files
Create a session in the project from New session, or use Add to project on an existing session. Review what changes in a project chat before moving it. Add reference files to the project.
-
Write project instructions (optional)
The agent uses the project instructions in each project session. Changes apply to the next turn.
Project roles
| Role | What the person can do |
|---|---|
| Owner | Manage access, instructions, and project settings. |
| Editor | Open the project and make changes, including sending messages in project sessions. |
| Viewer | Open the project, its sessions, and its files. Cannot make changes or send messages. |
In Project access, the owner sets Who can access to Only project members or Everyone in the organization. For organization access, the owner selects Can view or Can edit.
Project settings
- Agent approvals. Organization default follows the organization's approval settings. Manual approval asks before approval-governed actions, including read-only tools. Organization denials still apply. Older projects may show Automatic approval, legacy, which behaves like Organization default.
- Agent project files. Read-only, Create-only, or Read-write access for the agent to project files.
Only project owners can change these settings.
Project skills
As a project owner, open the project's skill list and select Create project skill. Save a draft, review its instructions and validation results, select the review checkbox, and click Release in followed by the project name. Complete identity confirmation if prompted. Only released revisions are available to project chats.
You can also copy a released private skill into a project. The copy starts as a separate project draft; later edits to the private skill do not automatically release changes to the project. Review and release the project copy. Release adds the skill to a custom project selection. Chats with their own saved selections still need you to add the skill in Session capabilities.
Back to contents ↑Scheduled Jobs
A scheduled job runs a prompt at a fixed time, for example a Monday sales digest or a nightly data check.
Creating a scheduled job
-
Test the prompt in a session
Run the task one time in a normal session. Make sure that the result is correct.
-
Go to Settings > Scheduled jobs
Click New job. Type a Job name and select a Time zone.
-
Set the schedule
Select Daily or Weekly and a time. For other schedules, select Custom and type a cron expression with five fields: minute, hour, day, month, weekday.
-
Type the prompt and save
Type the Prompt. Click Save paused to keep the job without running it, or Save and enable to start its schedule. Check that the job is enabled and review its next run time.
Run history
Click Runs on a job. Each run shows its status, start time, duration, and a summary when available. Failed or skipped runs can show a reason. Use Edit, Disable, Enable, and Delete to manage the job.
Keyboard Shortcuts
Press ? on any page to see the shortcuts. On a Mac, use ⌘ for Cmd. On other systems, use Ctrl.
| Keys | Action | Where |
|---|---|---|
Cmd/Ctrl+K | Jump to a page, session, or project | Everywhere |
? | Show keyboard shortcuts | Everywhere |
Cmd/Ctrl+Shift+O | New session | Chat |
Cmd/Ctrl+Shift+S | Show or hide the sidebar | Chat |
Cmd/Ctrl+. | Show or hide the artifacts panel | Chat |
/ | Write a message | Chat |
Esc | Stop the agent while it works | Chat |
Shortcuts without Cmd or Ctrl, except Esc, do not work while you type in a text field. Shortcuts do not work while a dialog or menu is open.
Back to contents ↑Platform Overview
As an admin, you control how Cogniplane works for your organization. You make models available, release skills and connections, set approvals and rules, configure PII protection, and manage people.
The Admin area
Admins and owners open Admin from the workspace menu. Members cannot open it. The Admin area has these pages:
| Page | What you control |
|---|---|
| Overview | Items that need attention (model budget, skill submissions, connections, models) and the status of each area. |
| Models | Provider API keys, available providers and models, default model, reasoning effort, and custom models. See Models & Providers. |
| Connections | MCP connections and built-in integrations. See Connecting an MCP Server and Built-in Integrations. |
| Skills | The skills library, imports, releases, and the review queue for member submissions. See Adding & Releasing Skills. |
| Agent behavior | Approval mode, read-only auto-approval, command execution, built-in tools, and organization instructions. See Agent Behavior & Policies. |
| People | Roles, test access, and removal of people. See People & Roles. |
| Policies | Ordered rules for MCP gateway tool calls, Monitor or Enforce mode, a rule test, and rule matches. |
| Privacy | PII protection mode, scan scope, retention of matched values, and findings. See Privacy. |
| History | A record of admin changes, with a comparison of settings versions. |
| Sessions | Session review: conversation, alerts, approvals, and diagnostics. |
| Usage | Token reports and the monthly model budget. |
| Feedback | Answer ratings that are on record, by day and by model. |
| Runtime diagnostics | Runtime sessions, backend configuration, and the Drain idle and Refresh idle actions. |
Policies was called Policy Center in earlier releases. Activity & Diagnostics describes the last five pages.
Architecture in brief
Cogniplane runs one agent runtime in the backend. Each session has its own state. When the owner allows command execution, shell and file commands run in a per-session E2B sandbox that Cogniplane creates on demand. The runtime reaches MCP connections through the MCP gateway on the backend loopback address. The gateway adds credentials, applies Policies rules, and records tool calls.
- The backend gives credentials to the gateway. The model does not supply identity.
- Tool calls through the gateway are recorded for audit.
- PostgreSQL row-level security scopes each tenant query to the requesting organization.
Security architecture for reviewers
For a formal security review, the controls are here:
| Control | Implementation |
|---|---|
| Authentication | Local accounts with passwords, MFA and optional passkeys, or WorkOS email sign-in and SSO. The deployment enables the supported methods. Access tokens (JWT) expire after 15 minutes. Refresh cookies are httpOnly and rotate on each use. A replay after a 60-second concurrency grace period revokes the whole token family. |
| Authorization | Owner, admin, and member roles, enforced at the API. Agent behavior, model availability, and Policies are enforced inside the runtime, not in prompts. |
| Data isolation | PostgreSQL row-level security scopes each tenant query to the requesting organization. Shell commands run in a per-session E2B sandbox. |
| Secret handling | Provider keys and connection secrets are write-only in the UI. Credentials are carried in short-lived per-turn tool contexts and are not given to the model. Tool results go through secret redaction before they are written to the audit trail. |
| Approval enforcement | The runtime stops each gated action until the person who started the turn decides. Requests expire after 10 minutes (default), and the action does not run. Each Policies approval is used one time. |
| PII protection | Off by default. When on, chat prompts, uploads, and Microsoft imports can be scanned. See Privacy. |
| Audit trail | Session review shows the conversation, tool calls, approvals, privacy scans, and audit events. History records admin changes. SIEM export is on the roadmap. |
| Hardening posture | URLs that users supply (skill imports, marketplace manifests) are blocked from private and reserved ranges. Admins can register MCP servers on private networks on purpose; the admin UI shows a warning. Uploads must match a MIME allowlist, and a binary file signature must match the declared type. Download filenames are encoded per RFC 5987. CI fails on any open dependency advisory, and production deploys run their own high-severity pnpm audit. |
Deployment & Hosting
The public demo uses a split frontend/backend topology. It is a preview environment for product evaluation. It is not evidence of a high-availability production service.
Current public demo layout
| Layer | Current platform |
|---|---|
| Frontend | Cloudflare |
| Backend | Containerized service on a single self-hosted machine |
| Backend ingress | Cloudflare Tunnel |
| Object storage | S3-compatible storage on the same host |
| Database | PostgreSQL |
| Redis | Redis |
Production deployment boundary
The demo keeps its stateful services on one host:
- It does not prove multi-host failover or a measured uptime target.
- Its repository does not install the documented off-host backup timer or Proxmox snapshot schedule.
- A production deployment must define its region, encryption, backup schedule, restore test, recovery targets, and incident owner.
Those production choices belong in the customer agreement and the operating runbook. Do not infer them from the demo.
Backend DNS and proxying
The public backend hostname points to a Cloudflare Tunnel. The tunnel gives two controls:
- DDoS protection and edge filtering in front of the API
- No public application port on the demo host
/mcp paths. The backend requires a loopback address for the runtime gateway URL, so MCP calls from the agent stay inside the backend host.
Request path in the public demo
-
The browser loads the frontend from Cloudflare
Cloudflare's edge network delivers the static assets and the public web pages.
-
The frontend calls the backend through the API hostname
That hostname resolves to the Cloudflare Tunnel.
-
The tunnel forwards allowed requests to the backend
The backend handles sign-in, sessions, the agent runtime, response streaming, and the MCP gateway.
-
The backend uses S3-compatible storage, PostgreSQL, and Redis on the same host
This is sufficient for the demo, but it does not give multi-host failover.
Models & Providers
Cogniplane runs one agent runtime that can use several model providers. The model selected for a session decides which provider runs. Configure models on the Models page.
| Provider | Models |
|---|---|
| Anthropic | Claude models |
| OpenAI | GPT models |
| Gemini models | |
| OpenRouter | Models routed through OpenRouter |
| Z.AI | GLM models on the Z.AI API |
When a model is available
Members can select a model only when all of these conditions are true:
- The provider is on in Providers.
- The provider has an API key. An owner saves the organization key on the Models page. The operator can also set a platform key for all organizations.
- The model is allowed in Available models. All models includes new catalog models automatically. Only selected models is a strict allowlist.
API keys are write-only. The UI does not show a saved key again.
Default model and custom models
- Default model. The model that new chats start on. If you select Catalog default, Cogniplane uses the default model of the catalog.
- Custom models. Click Add model to add a model ID that is not in the catalog. Give a display name and a context window. For OpenRouter, search the OpenRouter catalog by slug.
Reasoning effort
Models that support extended reasoning accept an effort level. Cogniplane converts the level to the setting of each provider. Higher effort uses more tokens, so it costs more and takes longer.
The chat picker does not show the effort by default. To show it, open Reasoning effort and select Show reasoning effort in the chat picker. You can also set a default effort for each model.
Where code runs
The agent runtime runs in the Cogniplane backend. When the owner allows command execution, shell and file commands run in a per-session E2B sandbox. Cogniplane creates the sandbox on demand and copies the session files into it. Without command execution, Cogniplane attaches no sandbox, and the agent cannot run shell commands.
Command execution and network access are separate settings. With no approved hosts, sandbox commands have no outbound network access. Configure Sandbox network access before asking the agent to download packages or reach a website.
Reasoning and plan streaming
Reasoning text and plan steps from the model stream into the conversation with the tool calls.
Adding & Releasing Skills
A skill gives the agent instructions for one type of work. The agent sees the name and description of each available skill. It opens the full instructions when a request matches.
On the Skills page, click Add skill. There are four ways to add a skill:
- Marketplace. Import an entry from a skill marketplace. Set the marketplace manifest URL on the same page.
- GitHub. Import a skill folder from a GitHub repository.
- ZIP upload. Upload a ZIP file that contains one skill folder.
- Paste SKILL.md. Type a Skill ID, a Display name, a Description, and the instructions.
Member submissions
Members can write private skills and submit a revision for review. Submissions appear in the Review tab of the Skills page and on the Overview page.
Back to contents ↑Anatomy of a Skill
A skill is a folder. The folder contains a SKILL.md file. SKILL.md starts with YAML frontmatter between two --- lines. Markdown instructions follow the frontmatter.
--- name: hr-policy-advisor description: Answers HR policy questions with the company policy pages. Use it for benefits, time off, leave, expenses, and conduct questions. metadata: owner: "People team" version: "1.0" --- # HR Policy Advisor ## Instructions You are an HR policy advisor for ACME Corp. Cite the policy page and section in each answer. If a policy is not clear, say so and tell the user to contact HR. Do not guess about policies that you cannot find. ## Workflow 1. If the question is not clear, ask one question to clarify it. 2. Search the HR policy pages. 3. Write a short answer with citations. 4. Offer related policies if they help. ## References - references/benefits-summary.md
Frontmatter reference
| Field | Required | Rules |
|---|---|---|
name | Yes | 1–64 characters. Lowercase letters, numbers, and single hyphens. It must be the same as the skill folder name. |
description | Yes | 1–1024 characters. Say what the skill does and when to use it. The agent selects skills from this text. |
license | No | Text. |
compatibility | No | 500 characters or fewer. |
metadata | No | A map of keys to string values. Put quotes around numbers, for example "1.0". |
allowed-tools | No | A space-separated list. Cogniplane shows it to reviewers as Declared tools. |
allowed-tools is metadata only. The tools that the agent can use come from Agent behavior, the connections released to the person, the session capabilities, and Policies.
The instructions body
Cogniplane does not require headings in the body. Use sections that make the instructions easy to follow, for example Instructions, Workflow, and References.
Writing Your First Skill
For a short skill, use Paste SKILL.md. For a skill with companion files, make a bundle and import it as a ZIP file or from GitHub.
-
Make the skill folder
Give the folder the skill name, for example
hr-policy-advisor. Use lowercase letters, numbers, and single hyphens. -
Write the frontmatter
In
SKILL.md, writename(the same as the folder name) anddescription. Write the description so that the agent knows when to use the skill. -
Write the instructions
This is the most important part. Tell the agent its role, what to focus on, what to do when it is not sure, and the hard limits (for example, "do not give legal advice").
-
Add companion files (optional)
Put them in
references/,assets/, orscripts/. Refer to them by path in the instructions. -
Check tool access
Make sure that the connections the skill needs are released to the same people. Use Policies rules if some tool calls need confirmation or a block.
-
Import, review, and release to test users
Import the skill. Review the new revision. Release it to Test users, test it in a session, then release it to All members.
Importing a Skill Bundle
A bundle is a skill folder in a ZIP file or in a GitHub repository. The validator checks the bundle before Cogniplane makes a revision.
Bundle structure
hr-policy-advisor/ # Folder name = the name in SKILL.md ├── SKILL.md # Required ├── README.md # Optional ├── LICENSE # Optional ├── references/ # Optional │ └── benefits-summary.md ├── assets/ # Optional └── scripts/ # Optional
Validation rules
- The skill root can contain only
SKILL.md,README.md,LICENSE, and the foldersassets/,references/, andscripts/. SKILL.mdmust start with YAML frontmatter. The frontmatter must havenameanddescription.- Symbolic links are not allowed.
- Limits: 50 files, 10 MB per file, and 25 MB in total.
Using the marketplace
A marketplace is a manifest that lists skills. Each entry names a repository, a Git ref, and a folder. Each entry also shows a review status (official, reviewed, community, or experimental), a publisher, and tags.
-
Set the manifest URL
On the Skills page, save the marketplace manifest URL for your organization.
-
Examine the entry
Read the review status, the publisher, and the source before you import.
-
Import the skill
Click Add skill > Marketplace and import the entry. The import makes a revision that waits for review.
Importing a bundle
-
Prepare the ZIP file
Put the skill folder in the ZIP file, for example
hr-policy-advisor/SKILL.md. Do not putSKILL.mdat the top level of the ZIP file. The ZIP file must contain exactly one skill. -
Open Skills and click Add skill
Select the ZIP upload tab.
-
Select the file and click Import ZIP
If the validation fails, Cogniplane shows the errors. Correct the bundle and upload it again.
-
Review the revision
Read the instructions, the declared tools, the validation results, and the file list. Then release the revision or save it as a draft.
-
Find the skill folder
The skill must be in a folder that has the skill name, for example
skills/hr-policy-advisor. Onlygithub.comover HTTPS is supported. -
Open Skills and click Add skill
Select the GitHub tab.
-
Enter the repository URL, the ref, and the subdirectory
Type the GitHub repository URL. Type a Ref (branch, tag, or commit). Use a tag or a commit for a repeatable import. Type the Subdirectory of the skill folder. You can also paste a
treeURL that includes the ref and the folder. -
Click Import GitHub skill and review the revision
Cogniplane downloads the folder and applies the same validation as a ZIP import.
Reviewing & Releasing a Skill
People can use an organization skill only after an admin releases a revision. The skill status on the Skills page tells you its state. Private skills and project skills have their own release controls.
The skill states
| Status | Meaning |
|---|---|
| Awaiting review | A revision was imported. No revision is released. Nobody can use the skill. |
| Available to test users | Released to people with test access only. |
| Available to members | Released to all members of the organization. |
| Off | Disabled. Nobody can use the skill. Click Re-enable to release it again. |
Releasing a revision
-
Open the revision
On the skill, click Review and history. Select the revision.
-
Review the revision
Read the instructions, the declared tools, the validation results, the provenance, and the files. Add Review notes if necessary.
-
Choose who can use the skill
Under Who can use this skill?, select Test users or All members.
-
Preview and confirm
Click Preview release to see the impact. Then click Confirm release and complete identity confirmation if prompted. The release applies on the next turn of each session. To stop without a release, click Save as draft.
Changing the audience or turning a skill off
- Make available to members. Moves a skill from test users to all members.
- Limit to test users. Moves a skill from all members back to test users.
- Disable. Turns the skill off for everyone.
Test access is set per person on the People page. Test users can use the skill releases and connections that an admin released to test users.
Rolling back a skill
To roll back, click Review and history, select an earlier revision, and release it. The rollback applies on the next turn of each session.
Reviewing member submissions
-
Open the Review tab
On the Skills page, select Review. The tab shows the number of pending submissions.
-
Read the submission
The submission shows the exact revision that the member sent and the note to reviewers.
-
Decide
Select Accept as organization draft, Request changes, or Decline. An accepted submission becomes an organization draft. It is not released until you release it.
Connecting an MCP Server
MCP (Model Context Protocol) servers give the agent access to company data and services. Each server exposes tools: named operations that the agent can call. Manage MCP servers in Connections > MCP connections.
Before you connect an MCP server
- The URL of the MCP server. The Cogniplane backend must be able to reach it.
- The credential that the server needs, if any: a bearer token, a header value, or a query parameter value.
- A decision about the account: one organization account, or one account for each member.
Adding an MCP connection
-
Open Connections and click Add connection
Type a Name, the URL, and a Description. Cogniplane warns you about an
http://URL or an address on a local network. -
Open Advanced settings
Keep Mode set to Proxy for a remote MCP server.
-
Choose the account for this connection
Organization account: all people use one credential that you save. Each member connects: each person saves a personal credential in Settings > Connected accounts.
-
Set the upstream authentication
Select None, Bearer token, Custom header, or Query parameter. For a header or a parameter, type its name. For an organization account, type the Secret. For Each member connects, select an option other than None. Secrets are write-only.
-
Set the availability
Select Off, Test users, or All members. Release to test users first. Then click Add connection and complete identity confirmation if prompted.
-
Test the saved connection
Click Test saved version. The test reports Reachability, Authentication, and Tool discovery with the number of tools seen. The test runs discovery only. No tool runs. For Each member connects, the test checks your own credential only.
Tool descriptions matter
The agent selects a tool from its name and description. A vague description causes wrong tool selection. If the agent does not call a tool when you expect it, improve the tool description on the MCP server.
Back to contents ↑Built-in Integrations
Built-in integrations are connectors that Cogniplane supplies. They have a fixed tool set and a sign-in flow for each user. Manage them in Connections > Built-in integrations.
What ships today
| Integration | What the agent can do | Accounts and setup |
|---|---|---|
| Notion | Reads: search, fetch pages, query databases. Writes: create pages, update pages, append blocks. | Each user connects a Notion workspace with OAuth. The operator sets NOTION_OAUTH_CLIENT_ID, NOTION_OAUTH_CLIENT_SECRET, and NOTION_OAUTH_REDIRECT_URI. |
| GitHub | Reads: read files. Writes: write files, open pull requests. Only in repositories that the connected user can access. | Each user connects a GitHub account with OAuth. The operator sets GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, and GITHUB_OAUTH_REDIRECT_URI. |
| Jira | Read-only: list sites, search issues with JQL, read issue details and change history. The agent cannot create, edit, or comment on issues. | Each user connects a Jira Cloud account through Pipedream and selects one Jira site. The operator sets PIPEDREAM_CLIENT_ID, PIPEDREAM_CLIENT_SECRET, and PIPEDREAM_PROJECT_ID. |
| Microsoft 365 | Reads: list SharePoint sites, browse and search files, read content. Writes: upload files, create folders, import a file into a session. | Included in Core and Cloud. The operator sets MICROSOFT_OAUTH_REDIRECT_URI. An admin saves the Microsoft Entra app's Application (client) ID, Client secret, and Directory (tenant) ID. Each user then connects a Microsoft account. |
These integrations use each member's personal account in standalone chats. Project chats exclude those accounts. Use an organization MCP connection for a service that a project needs. See the connector setup guide for redirect URLs and permissions. Microsoft users must reconnect after writes are enabled if their original consent covered reads only.
The list also shows integrations marked Coming soon. You cannot enable them.
How to enable an integration
-
Make sure the platform is configured
If the operator did not set the environment variables, the integration shows Platform not configured.
-
Turn on Reads, Writes, or both
Each integration has a Reads switch and a Writes switch. Turn on reads first. Watch the use, then turn on writes. Use Policies in Monitor mode to collect evidence before you enforce rules.
-
Configure the integration if necessary
An integration that needs organization credentials shows Configure. Secrets are encrypted at rest and are not shown again. Complete identity confirmation if prompted when saving protected settings.
-
Users connect their accounts
Each user connects in Settings > Connected accounts or on the integration page in Settings. The credentials go to the agent runtime for each turn. They do not go to the model.
Agent Behavior & Policies
Agent behavior sets how the agent works for the whole organization. Policies adds ordered rules for tool calls that go through the MCP gateway.
Agent behavior
| Setting | What it does |
|---|---|
| Approvals | Require approval (default): the agent asks before actions that are not read-only. Never require approval: skips ordinary native approval prompts. Mandatory approvals, such as exact-text memory saves, and Policies rules still apply. |
| Auto-approve read-only tools | On by default. Read-only tools run without a prompt. A project set to Manual approval ignores this setting. |
| Command execution | Off by default. When on, the agent can run shell commands in a sandbox. Only an owner can change this setting. |
| Sandbox network access | The approved hosts that sandbox commands can reach. An empty list denies outbound network access. See setup and limits. |
| Built-in tools | The built-in tools the agent can use, for example session files, project files, and memory. Click Choose tools. |
| Organization instructions | A Custom system prompt added at the start of every chat. Up to 4,000 characters. |
To save, click Review changes. The review dialog lists each change and marks changes that widen access. Confirm the save and complete identity confirmation if prompted. Each save makes a new settings version. History can compare versions.
Sandbox network access
In Agent behavior, open Sandbox network access and edit Approved hosts. Enter one host per line, such as pypi.org and files.pythonhosted.org for Python package downloads. Do not enter URLs, IP addresses, or ports. example.com does not include its subdomains; *.example.com includes subdomains but not the root host.
Review the hosts and save the settings. A sandbox whose network policy no longer matches is replaced before a later turn uses it. Files saved only in that sandbox are lost. With an empty list, outbound access is denied. While any host is approved, all traffic to the sandbox's DNS resolver, 8.8.8.8, is also allowed, including DNS over HTTPS. Data can leave through lookup names. The host filter trusts the name stated by the request, so the list is not a complete data-loss-prevention boundary. See the sandbox network reference for details.
Policies
A rule matches tool calls that go through the MCP gateway: MCP connections, integration tools, and Cogniplane built-in tools such as session files, project files, and memory. Rules do not govern sandbox shell and file commands, which use runtime approvals.
| Rule part | Values |
|---|---|
| Effect | Allow, Require actor confirmation, or Block. |
| Tool names | A comma-separated list. Empty means any tool. |
| Categories / servers | A comma-separated list. Empty means any. |
| Severities | Read-only or File change. |
| Turn context | Interactive or Scheduled / unattended. |
| Explanation shown to the user | Optional text that the user sees when the rule applies. |
How rules are evaluated
- Rules have a priority order. Drag the handle of a rule to change the order.
- The first enabled rule that matches decides. The next rules are not checked.
- A tool call that matches no rule is allowed.
- Require actor confirmation asks the person who started the turn. Each confirmation is for one call only. In a scheduled run, nobody can confirm, so the call is denied.
Monitor and Enforce
Policies has one mode for the organization. The default is Monitor.
- Monitor. Cogniplane records each rule match. Rules do not block or ask.
- Enforce. Matching Block rules block the call. Matching Require actor confirmation rules ask for confirmation.
To switch to Enforce, click Review enforcement. The dialog shows the evidence from the last 7 days. To go back, click Switch to Monitor. Rule matches lists each match: Applied in Enforce, Recorded only in Monitor.
Testing and checking rules
- Test a tool call. Type a tool name, a category or server, a severity, and a turn context. Click Run test to see which rule matches and what happens in each mode.
- Rule checks. Cogniplane marks problem rules. Unreachable: an earlier rule always matches first. Duplicate: an earlier rule has the same conditions. Unknown condition: a condition key is not valid.
Privacy (PII Protection)
Cogniplane can scan chat prompts, uploads, and Microsoft imports for personally identifiable information (PII). PII protection is off by default. Configure it on the Privacy page.
Protection mode
| Mode | Behavior |
|---|---|
| Off | No PII scans run. |
| Detect | Scans and reports findings to admins. The original content continues to the agent and can reach the selected model provider. |
| Block | Checks content before use and rejects it when a match is found. A blocked upload is unavailable; its stored object is deleted, with retries if cleanup fails. |
| Transform | Redacts matches in chat prompts before the agent receives them. For uploads and imports, Transform only reports findings, like Detect. |
Where to scan
Select the scopes: Chat prompts, Direct uploads, and Microsoft imports. Scheduled job prompts go through the chat prompt check at each run.
Uploads and imports support plain and structured text, shell scripts, and PDF text. The default file scan limit is 5 MB. Rules scan the whole CSV file; the detection model receives a bounded preview of its header and first rows. Office files and standalone images are not supported by the scanner and are rejected when their upload or import protection scope is on.
PDF text and images
PDF text is extracted before scanning. By default, OCR is off and the verdict says text only; images in that PDF have not been scanned. A PDF with no extractable text is rejected unless OCR supplies text.
The operator can enable local OCR with PII_PDF_OCR_ENABLED. It reads PDF page images on the backend and sends the extracted text through the same PII checks. With OCR enabled, Block mode rejects a PDF when image scanning is incomplete. Detect and Transform can record images partly scanned or image scan failed instead. Even complete OCR can misread text. See PDF OCR setup and limits.
Detection
A locally operated detector keeps the detection request local. It does not prevent the agent from sending content to its model provider. Detect leaves the content unchanged, and Transform changes chat prompts only. Choose the mode and scopes for the data you intend to protect.
- Rules. Deterministic rules find structured values such as email addresses and phone numbers.
- Detection model (optional). The operator turns it on with
PII_PROVIDER_ENABLEDand pointsPII_LLM_BASE_URLat any OpenAI-compatible endpoint. On the Privacy page, you can select a model on that endpoint. - Personal data types. Email, Phone, Person name, Address, Financial, and Government ID.
Matched values
- Do not keep matched values. Findings do not include the matched text.
- Keep values for admins. Findings include the matched text. Only admins can see it.
- Keep encrypted values. Findings store the matched text encrypted. The server needs a PII retention key, or scans fail.
Audit and evidence
The Privacy page shows PII activity and findings. In session review, the Privacy scans view shows the scans for each message and file.
Weakening protection or keeping more matched data can require identity confirmation and notify owners.
Back to contents ↑Organization, People & Roles
Cogniplane is multi-tenant. Each organization is its own tenant. PostgreSQL row-level security keeps the users, sessions, skills, and data of one organization separate from other organizations.
Roles
| Role | What the person can do |
|---|---|
| Owner | All admin access. Changes roles. Changes owner-only settings: provider API keys and command execution. |
| Admin | Manages models, connections, skills, policies, and people. Can remove members. Cannot remove admins or change roles. |
| Member | Uses the workspace with the skills and connections released to members. No access to Admin. |
Adding people
For a local-account organization, use Add person in People. Enter the person's email and permitted role, then confirm. Complete identity confirmation if prompted. When email delivery is configured, Cogniplane sends a setup link. Otherwise, the manager receives a link to share with the person. The person sets a password and completes any required second-factor enrollment.
For a WorkOS organization, manage access through the identity provider. A person appears in People after their first permitted sign-in. The operator configures which sign-in types the deployment supports.
Local account security
The person page provides local-account setup and reset actions. Complete identity confirmation if prompted for setup, password or MFA resets, disabling or enabling an account, or removal. Owners can manage admins; admins can manage members. Managers cannot use these actions on themselves or an owner. A new local account must complete setup before it can be promoted to owner.
The organization MFA policy can be Optional, Required for owners and admins, or Required for everyone. Complete identity confirmation if prompted when changing the MFA policy. A registered passkey also satisfies the second-factor requirement. Local users manage their authenticator, passkeys when enabled, and recovery codes in Settings > Sign-in & security. WorkOS account security stays with the identity provider.
Confirming sensitive changes
A local sign-in session must supply fresh proof for protected actions, such as adding or managing local members, changing the MFA policy, changing provider keys or data destinations, weakening Policies or PII controls, and releasing organization or project skills. Review the action in the confirmation dialog. Use your authenticator or passkey if the account has a second factor; otherwise use your password. The proof applies once to that action.
WorkOS sessions do not use this Cogniplane identity-confirmation mechanism. Protected data-route changes, weaker controls, and shared skill releases also queue notices to organization owners. Email delivery must be configured and the owner must have an email address. With email off, the audit event remains the record. See the sensitive-change reference for the covered actions.
Changing a role
-
Open People and select the person
The person page has Access, Activity, and Skills & connections.
-
Change the role in Access
Select the new role, read the effects, and confirm. Complete identity confirmation if prompted. The change applies to the next request of the person.
- Only owners can make a person an admin or an owner.
- Only owners can change the role of an admin.
- Nobody can demote or remove an owner. Making a person an owner is permanent.
Test users
On the person page, turn on Test access. Test users can use the skill releases and connections that an admin released to test users. Unreleased drafts stay hidden.
Removing a person
In Access, click Remove from organization and complete identity confirmation if prompted. When you remove a person:
- They lose access to this organization on their next request.
- Their scheduled jobs are turned off, and agent runs in progress stop.
- Their personal skills, personal tool choices, and saved credentials for organization connections are deleted.
- Cogniplane tries to delete their connected accounts, such as GitHub or Notion. It cannot guarantee revocation at the external service.
Their past sessions are not deleted. You cannot undo a removal. Admins can remove members. Only owners can remove an admin.
GitHub setup
GitHub uses one model: each user connects a personal GitHub account with OAuth. There is no organization GitHub App.
-
The operator registers a GitHub OAuth app
The operator sets
GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET, andGITHUB_OAUTH_REDIRECT_URIin the backend environment. -
An admin enables GitHub
In Connections > Built-in integrations, turn on Reads and, if necessary, Writes.
-
Each user connects GitHub
In Settings > GitHub or Connected accounts. The agent then works in the repositories that the user can access.
Activity & Diagnostics
History
History lists admin changes, newest first, in UTC. Filter by category: Settings, Policies, People, Models, Connections, Skills, Budgets, or Runtime. Open a record to see its details. For a settings change, use Compare with to compare two recorded versions. The view does not show personal activity or secret values. A missing record does not prove that no change occurred.
Sessions
Sessions lists the sessions of the organization with filters. Open a session to review it:
- Conversation. A replay of the messages.
- Alerts. Problems found in the session, for example failures, approvals, and PII findings.
- Approvals. Each approval request and its result.
- Diagnostics. Session details, Tool calls, Files, Privacy scans, Audit events, and Raw messages.
Usage and model budget
Token reports show tokens and estimated cost for a report period, by user and by model. Costs come from model prices, not from provider invoices.
Model budget sets a monthly limit on estimated model cost. Click Set a limit or Change budget and select one option:
- Set a monthly limit. Each new turn reserves an amount, by default $1. New turns start only when the budget has room for another reservation. Before each model call, Cogniplane checks the cost already recorded for that turn. A call already in progress can exceed the reservation.
- No limit. New turns start without a hold. The budget does not count them.
- Pause new turns. A limit of $0. No new chat or scheduled turn can start.
The budget counts estimated model cost only. It does not count sandbox execution, storage, external tool services, or PII processing. Changes apply to new turns.
When all usage is known and no provider call failed, settlement releases the unused reservation. Failed or incomplete usage can retain charges. Unknown usage for the current month blocks new model work until an administrator reconciles it, even if the page appears to show room in the budget.
For an unresolved reservation, ask the person running the chat to stop it. For scheduled work, ask the job owner to disable future runs and wait for the current run to end. Disabling a job does not stop its active run. If the reservation is still active, close it to stop new model calls under it. Closing does not cancel provider requests or refund the hold. Confirm with the person responsible and provider records that all requests have ended. Get the complete cost, then use Record verified cost to reconcile the reservation. This is estimated-cost admission control, not a strict provider billing cap. See model spending and recovery.
Feedback
Feedback shows the answer ratings on record: thumbs up and thumbs down, a daily breakdown, and a breakdown by model. The current chat has no rating control, so members cannot add new ratings from the chat.
Runtime diagnostics
Runtime diagnostics lists runtime sessions. Filter by session or runtime ID, and by status. Backend configuration shows the E2B template and which platform provider keys are set. Refresh idle and Drain idle both close the idle runtime sessions of the organization. The next turn of each session starts with the current configuration. Sessions with a running turn are not affected. The agent workspace of each closed session is reset, so files that the agent made only in the sandbox are lost.
Back to contents ↑