Documentation

Cogniplane docs for governed AI work.

Cogniplane gives your organization one governed place for AI work: research, drafting, analysis, and multi-step tasks. Organization, personal, and project skills work within the organization's controls for access, approvals, and audit.

Documentation

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.

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.

💡
New here? If someone else set up Cogniplane for you, go to Getting Started. If you are responsible for the platform, go to the Admin Guide.
Back to contents ↑
For Users

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.

💡
Use your organization's sign-in method. A local setup link and a WorkOS account are different sign-in paths. If the method or setup link you need is missing, contact your Cogniplane administrator.

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

  1. Click New session

    Select Personal session or a project, then click Create session. A personal session is private to you.

  2. 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").

  3. Watch the agent work

    Tool calls appear in the conversation. When an action needs your approval, an approval card appears. See Tool Actions & Approvals.

  4. Continue the conversation

    The agent keeps the full conversation of the session. Ask follow-up questions, correct the agent, or change the task.

Back to contents ↑
For Users

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.
ℹ️
Tool calls are visible. Each tool call is in the conversation, so you can check where the data came from. A model can still make errors. Check important facts against the tool results.

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 ↑
For Users

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

  1. Click Session capabilities in the header

    The dialog lists the skills and connectors for the session.

  2. Select Choose for this session

    Clear the skills and connectors that you do not want. Organization policy always applies.

  3. 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.

  1. Go to Settings > Skills & connections

    Under Private skills, click Create skill.

  2. 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.

  3. 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 ↑
For Users

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.

You send a message
→
The agent calls a tool
→
Read-only tool runs
→
Answer appears

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.

The agent plans an action
→
Approval card appears
→
You decide
→
Action runs or stops

Your choices

ButtonResult
DeclineThe action does not run. The agent continues and can try a different approach.
Approve onceThis action runs. The next action of the same type asks again.
Allow for this turnWhen 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.
⚠️
Only you can approve your turn. The person who started the turn is the only person who can approve or decline its actions. Read the card before you click Approve once or Allow for this turn.
ℹ️
Approvals expire. An approval request that gets no answer expires after 10 minutes (default). The action does not run, and an Approval expired notice appears. If you stop the turn, Cogniplane cancels its pending approvals.

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
Back to contents ↑
For Users

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

  1. Open the artifacts panel

    Click the panel button in the header, or press the shortcut. Select the Context tab.

  2. 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.

  3. 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

TypeFormats
Text and dataPlain text, Markdown, CSV, JSON, HTML
CodePython, TypeScript, JavaScript, shell scripts
DocumentsPDF, Word (.docx), Excel (.xlsx)
ImagesPNG, 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.

ℹ️
Uploads can be scanned for PII. When upload protection is on, supported text files and PDF text are scanned before use. The default scan size limit is 5 MB. Optional OCR scans PDF page images; without it, a PDF scan covers text only. Unsupported files, such as Office files and standalone images, are rejected while upload protection is on. See Privacy for modes and coverage limits.

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 ↑
For Users

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 ↑
For Users

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.

💡
Who can see a session. A personal session is private to you. A project session is visible to the people with access to the project. Admins can review sessions in Admin for audit.
Back to contents ↑
For Users

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

  1. Click Projects in the sidebar

    Type a name and click Create project.

  2. 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.

  3. Write project instructions (optional)

    The agent uses the project instructions in each project session. Changes apply to the next turn.

Project roles

RoleWhat the person can do
OwnerManage access, instructions, and project settings.
EditorOpen the project and make changes, including sending messages in project sessions.
ViewerOpen 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 ↑
For Users

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

  1. Test the prompt in a session

    Run the task one time in a normal session. Make sure that the result is correct.

  2. Go to Settings > Scheduled jobs

    Click New job. Type a Job name and select a Time zone.

  3. 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.

  4. 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.

ℹ️
Scheduled jobs run as you, with no one to approve. Each run starts a new session under your identity. Your organization's settings, Policies rules, and PII protection apply at each run. A scheduled run cannot ask for approval. An action that needs approval does not run. A Policies rule that requires confirmation denies the action in a scheduled run. By default, a run stops after 5 minutes, and Cogniplane disables a job after 5 failed runs in a row.
Back to contents ↑
For Users

Keyboard Shortcuts

Press ? on any page to see the shortcuts. On a Mac, use ⌘ for Cmd. On other systems, use Ctrl.

KeysActionWhere
Cmd/Ctrl+KJump to a page, session, or projectEverywhere
?Show keyboard shortcutsEverywhere
Cmd/Ctrl+Shift+ONew sessionChat
Cmd/Ctrl+Shift+SShow or hide the sidebarChat
Cmd/Ctrl+.Show or hide the artifacts panelChat
/Write a messageChat
EscStop the agent while it worksChat

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 ↑
For Admins

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:

PageWhat you control
OverviewItems that need attention (model budget, skill submissions, connections, models) and the status of each area.
ModelsProvider API keys, available providers and models, default model, reasoning effort, and custom models. See Models & Providers.
ConnectionsMCP connections and built-in integrations. See Connecting an MCP Server and Built-in Integrations.
SkillsThe skills library, imports, releases, and the review queue for member submissions. See Adding & Releasing Skills.
Agent behaviorApproval mode, read-only auto-approval, command execution, built-in tools, and organization instructions. See Agent Behavior & Policies.
PeopleRoles, test access, and removal of people. See People & Roles.
PoliciesOrdered rules for MCP gateway tool calls, Monitor or Enforce mode, a rule test, and rule matches.
PrivacyPII protection mode, scan scope, retention of matched values, and findings. See Privacy.
HistoryA record of admin changes, with a comparison of settings versions.
SessionsSession review: conversation, alerts, approvals, and diagnostics.
UsageToken reports and the monthly model budget.
FeedbackAnswer ratings that are on record, by day and by model.
Runtime diagnosticsRuntime 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.

⚠️
Changes apply on the next turn. When you save Agent behavior, release a skill, or change a connection, each session uses the new configuration from its next turn.

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:

ControlImplementation
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.
Back to contents ↑
For Admins

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

LayerCurrent 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
🛡️
The MCP gateway is not public. The tunnel returns 404 for /mcp paths. The backend requires a loopback address for the runtime gateway URL, so MCP calls from the agent stay inside the backend host.
⚠️
Production ingress needs its own review. Each customer deployment must restrict direct origin access and keep the MCP path private. The demo layout is one implementation, not a universal production design.

Request path in the public demo

  1. The browser loads the frontend from Cloudflare

    Cloudflare's edge network delivers the static assets and the public web pages.

  2. The frontend calls the backend through the API hostname

    That hostname resolves to the Cloudflare Tunnel.

  3. The tunnel forwards allowed requests to the backend

    The backend handles sign-in, sessions, the agent runtime, response streaming, and the MCP gateway.

  4. 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.

Back to contents ↑
For Admins

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.

ProviderModels
AnthropicClaude models
OpenAIGPT models
GoogleGemini models
OpenRouterModels routed through OpenRouter
Z.AIGLM 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.

💡
If members see no models. The chat shows No models are available. Check that at least one provider is on, has a key, and has an allowed model. The Overview page lists this problem.
Back to contents ↑
For Admins

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.
ℹ️
An import does not release the skill. Each import makes a new revision. The revision waits for review. You then release it to Test users or All members, or you save it as a draft. See Reviewing & Releasing.

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 ↑
For Admins

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.

hr-policy-advisor/SKILL.md — annotated example
---
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

FieldRequiredRules
nameYes1–64 characters. Lowercase letters, numbers, and single hyphens. It must be the same as the skill folder name.
descriptionYes1–1024 characters. Say what the skill does and when to use it. The agent selects skills from this text.
licenseNoText.
compatibilityNo500 characters or fewer.
metadataNoA map of keys to string values. Put quotes around numbers, for example "1.0".
allowed-toolsNoA space-separated list. Cogniplane shows it to reviewers as Declared tools.
⚠️
Skills do not grant or restrict 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.

💡
Write for the worst case, not only the usual case. Tell the agent what to do when it cannot find an answer, when the question is not clear, or when the request is outside the skill. Clear fallback steps give more consistent results.
Back to contents ↑
For Admins

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.

  1. Make the skill folder

    Give the folder the skill name, for example hr-policy-advisor. Use lowercase letters, numbers, and single hyphens.

  2. Write the frontmatter

    In SKILL.md, write name (the same as the folder name) and description. Write the description so that the agent knows when to use the skill.

  3. 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").

  4. Add companion files (optional)

    Put them in references/, assets/, or scripts/. Refer to them by path in the instructions.

  5. 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.

  6. 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.

ℹ️
Each import is a revision. To change a skill, import the new version. Earlier revisions stay in the history, so you can release one again. A revision cleanup can remove old revisions that are not in use.
Back to contents ↑
For Admins

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 folders assets/, references/, and scripts/.
  • SKILL.md must start with YAML frontmatter. The frontmatter must have name and description.
  • 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.

  1. Set the manifest URL

    On the Skills page, save the marketplace manifest URL for your organization.

  2. Examine the entry

    Read the review status, the publisher, and the source before you import.

  3. Import the skill

    Click Add skill > Marketplace and import the entry. The import makes a revision that waits for review.

Importing a bundle

  1. Prepare the ZIP file

    Put the skill folder in the ZIP file, for example hr-policy-advisor/SKILL.md. Do not put SKILL.md at the top level of the ZIP file. The ZIP file must contain exactly one skill.

  2. Open Skills and click Add skill

    Select the ZIP upload tab.

  3. Select the file and click Import ZIP

    If the validation fails, Cogniplane shows the errors. Correct the bundle and upload it again.

  4. 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.

  1. Find the skill folder

    The skill must be in a folder that has the skill name, for example skills/hr-policy-advisor. Only github.com over HTTPS is supported.

  2. Open Skills and click Add skill

    Select the GitHub tab.

  3. 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 tree URL that includes the ref and the folder.

  4. Click Import GitHub skill and review the revision

    Cogniplane downloads the folder and applies the same validation as a ZIP import.

ℹ️
Private repositories. If you connected your own GitHub account in Settings, Cogniplane uses it to download the repository. If you did not connect an account, the repository must be public. You can always use a ZIP import for a private bundle.
Back to contents ↑
For Admins

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

Awaiting review
→
Available to test users
→
Available to members
→
Off
StatusMeaning
Awaiting reviewA revision was imported. No revision is released. Nobody can use the skill.
Available to test usersReleased to people with test access only.
Available to membersReleased to all members of the organization.
OffDisabled. Nobody can use the skill. Click Re-enable to release it again.

Releasing a revision

  1. Open the revision

    On the skill, click Review and history. Select the revision.

  2. Review the revision

    Read the instructions, the declared tools, the validation results, the provenance, and the files. Add Review notes if necessary.

  3. Choose who can use the skill

    Under Who can use this skill?, select Test users or All members.

  4. 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

  1. Open the Review tab

    On the Skills page, select Review. The tab shows the number of pending submissions.

  2. Read the submission

    The submission shows the exact revision that the member sent and the note to reviewers.

  3. 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.

Back to contents ↑
For Admins

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.
💡
Building an MCP server? An MCP server is an HTTP service that implements the Model Context Protocol tool interface. The Cogniplane gateway adds the credentials and records the calls. Your MCP server is responsible for its own downstream authorization.

Adding an MCP connection

  1. 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.

  2. Open Advanced settings

    Keep Mode set to Proxy for a remote MCP server.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

ℹ️
Changes that make members reconnect. When you change the URL or the authentication method of a connection that uses Each member connects, each member must connect again.

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 ↑
For Admins

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

IntegrationWhat the agent can doAccounts 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

  1. Make sure the platform is configured

    If the operator did not set the environment variables, the integration shows Platform not configured.

  2. 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.

  3. 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.

  4. 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.

💡
The Settings menu shows enabled integrations only. The user Settings pages for GitHub, Notion, and Jira appear only when the integration is enabled for the organization.
ℹ️
Integrations vs. MCP connections. Cogniplane supplies the integrations and their tool sets. Your team builds or runs MCP servers for internal systems. Both send tool calls through the same gateway, the same Policies rules, and the same audit trail.
Back to contents ↑
For Admins

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

SettingWhat it does
ApprovalsRequire 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 toolsOn by default. Read-only tools run without a prompt. A project set to Manual approval ignores this setting.
Command executionOff by default. When on, the agent can run shell commands in a sandbox. Only an owner can change this setting.
Sandbox network accessThe approved hosts that sandbox commands can reach. An empty list denies outbound network access. See setup and limits.
Built-in toolsThe built-in tools the agent can use, for example session files, project files, and memory. Click Choose tools.
Organization instructionsA 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 partValues
EffectAllow, Require actor confirmation, or Block.
Tool namesA comma-separated list. Empty means any tool.
Categories / serversA comma-separated list. Empty means any.
SeveritiesRead-only or File change.
Turn contextInteractive or Scheduled / unattended.
Explanation shown to the userOptional 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.
💡
Recommended rollout. Add rules in Monitor mode. Read Rule matches for some days. Correct the rules. Then switch to Enforce.
Back to contents ↑
For Admins

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

ModeBehavior
OffNo PII scans run.
DetectScans and reports findings to admins. The original content continues to the agent and can reach the selected model provider.
BlockChecks 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.
TransformRedacts 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.

⚠️
What happens without the detection model. For chat prompts, Block and Transform need the detection model. If it is not configured or fails, the prompt is rejected. Detect uses rules only when no provider is configured or its circuit breaker is open; other provider errors fail the check. For uploads, the rules run and the detection model runs when configured. Block mode can use rules alone when no provider is configured, but a configured provider's error fails the scan. Unsupported files, unreadable PDFs, and files above the scan limit are rejected. Transform does not mask file content; it reports findings.

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_ENABLED and points PII_LLM_BASE_URL at 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 ↑
For Admins

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.

ℹ️
Access scope today. You can release skills and connections to the whole organization or to test users. A project gives access to its members or to the whole organization, as the project owner selects. Teams are planned for a future release.

Roles

RoleWhat 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

  1. Open People and select the person

    The person page has Access, Activity, and Skills & connections.

  2. 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.

  1. The operator registers a GitHub OAuth app

    The operator sets GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, and GITHUB_OAUTH_REDIRECT_URI in the backend environment.

  2. An admin enables GitHub

    In Connections > Built-in integrations, turn on Reads and, if necessary, Writes.

  3. Each user connects GitHub

    In Settings > GitHub or Connected accounts. The agent then works in the repositories that the user can access.

Back to contents ↑
For Admins

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 ↑