bin/ cockpit and cockpit-agent entrypoints
src/cli/ Arguments, startup, and shutdown
src/server/ Fastify, routes, WS, PTY, and durable sessions
src/core/ Runs, states, results, and evidence
src/persistence/ Local stores and atomic writes
src/orchestration/ Dispatch, supervision, dependencies, and race
src/isolation/ Worktrees, symlinks, and configuration
src/review/ Diffs, annotations, and reviews
src/adapter/ Events and session signals
src/transcript/ Parsers, sanitization, and handoff
src/services/ Projects, agents, catalogs, media, voice, and DSH
src/catalog/ Profiles and role contracts
src/types/ TypeScript contracts
web/ React, Vite, CodeMirror, and xterm
tests/ Unit, integration, and e2e tests
scripts/ Report generation
docs/ Specifications, plans, schemas, and audits
dist/ Generated backend
web/dist/ Generated interface
Reference files in the repository:
- Documentation index:
docs/README.md. - Canonical architecture:
docs/Cockpit.md. - Role contracts:
docs/ROLE_CONTRACTS.md. - Runtime, routing, and Brain plan:
docs/COCKPIT_AI_RUNTIME_AND_ROUTING_PLAN.md. - Race and frontiers specification:
docs/COCKPIT_P3_RACE_MODE_AND_FRONTIERS_SPEC.md. - Providers and quotas specification:
docs/COCKPIT_MULTI_PROVIDER_QUOTAS_SPEC.md. - Release/deployment plan:
docs/COCKPIT_RELEASE_AND_DEPLOYMENT_PLAN.md. - End-to-end acceptance:
docs/COCKPIT_END_TO_END_ACCEPTANCE_PLAN.md. - Invariant matrix:
docs/COCKPIT_INVARIANTS_COMPLIANCE_MATRIX.md. - Migration:
docs/COCKPIT_MIGRATION_2026-10-04.md. - Result schema:
docs/schemas/worker-result.schema.json.
Audits reflect their creation date. For current behavior, inspect the installed revision's code, scripts, and checks.
#DSH tool mode
When creating or configuring a DSH member, choose Default (direct tool calls) or PTC mode (programs coordinating tools through run_code). Cockpit loads the DSH code runtime for PTC and shows the mode in the conversation header. Existing sessions retain their mode; apply changes and restart the member to switch.
Permissions remain independent: Read only, Project write, or Full access. PTC does not grant extra access. Full access allows actions outside the project under DSH policies.
Both modes load Cockpit's MCP bridge automatically with session identity and authentication. Internal DSH subagents are disabled to preserve your configured team. Conversation and technical output show responses, tools, and errors; reasoning blocks are neither displayed nor saved in chat history.
After updating with old DSH sessions, stop panels and restart Cockpit before creating members. Old session services do not load new code; a service without the current bridge is rejected for new DSH sessions. Existing history is preserved.
#Diagnostics and protected remote access
After npm run setup, run npm run doctor (or cockpit --doctor). Diagnostics do not start the server. They check Node, Git, Bash, project write access, web build, voice engine, and OpenSSL for local certificates. The same results appear in Settings → Installation. Under Connections, use Test connection to validate agents: a configuration file does not prove authentication. Run the Windows server inside WSL2; the Windows browser can be a client.
Local access without a token remains available. Network REST/WS clients require pairing or a master token. Network invitations require HTTPS; HTTP invitations are limited to loopback.
On the server via localhost, open Settings → Administration → Generate certificate and enable HTTPS (default port 4443). Download the public certificate and install it as a trusted authority on each device. Open one of the displayed HTTPS addresses, then Remote access to create an invitation. HTTPS adds a listener to the same server without interrupting missions or terminals; agents keep their local bridge connection. Certificates/configuration live in .cockpit/tls and .cockpit/https-admin.json, and HTTPS is restored at startup.
Renew certificate includes current IPs while preserving the installed authority. Choose a free port if needed. If started with --tls-cert, Cockpit retains that supplied certificate and its renewal configuration.
Alternatively, npm run setup:https creates a local authority under ~/.cockpit/tls and a certificate for current IPs, localhost, and 127.0.0.1. It prints the exact startup command including NODE_EXTRA_CA_CERTS so agent CLI/MCP connections trust it. Install only ca.pem as a trusted authority on clients. Keep private keys ca-key.pem and key.pem on the server; never share them. Trust installation depends on the client OS and is not automatic. Regenerate when the IP changes or the certificate expires; the existing authority is preserved.
You can use an existing PEM certificate:
npm start -- --host 0.0.0.0 --tls-cert /path/to/certificate.pem --tls-key /path/to/key.pem
It must cover the client's address and 127.0.0.1 for the local agent bridge, and Node must trust its issuer. Equivalent variables: COCKPIT_TLS_CERT and COCKPIT_TLS_KEY. Never disable TLS validation. For a local reverse proxy, also configure COCKPIT_TOKEN and protect/forward authentication, since the backend sees the proxy as local.
In Settings → Remote access, enter the HTTPS URL, select Check address, and create an invitation. Verification checks that the URL reaches the same server. View is read-only; Control permits tasks, reviews, and terminals. Invitations are single-use and expire in five minutes; sessions last 24 hours. Revoke devices there too.
For updates, stop the server normally (agents are preserved), back up .cockpit and configuration under ~/.cockpit, update the code, and run npm run setup and npm run doctor before restarting. To restore, stop the server, return to the corresponding code version, and restore the backups. Never copy actively changing storage.
#Agent suggestions with Jev
In Settings → Connections → TypeSafe / Jev, save a TypeSafe key, enable suggestions, and select Test Jev. Saving makes no external call; tests and queries may consume credits. The server encrypts the key.
Open Progress → Activity → Team tools → Suggest an agent for a task. Enter a summary and category, check candidates, and permit sending that context. Suggestions show member, probabilities, and confidence. Apply suggestion fills the recipient and message for review; sending is separate. Only open, available agents participate. TypeSafe failures produce a local selection with an explanation. Recent suggestions shows history. See docs/JEV_INTEGRATION.md.
The Jev bar shows status, decisions, and a per-mission switch. In Directed and Autonomous modes, Maestro uses Jev when delegating to a role or auto, among available authorized specialists. Explicit IDs preserve the chosen recipient. History links Maestro delegations with resulting tasks. Queries may send task titles/descriptions and candidates and consume credits. Disabling Jev or provider failures preserve local delegation. Free mode uses manual queries. Jev does not change models or runners.
Connect agents selects all specialists or a subset, even without Maestro, such as Builder and Explorer for manual queries. Connecting starts neither tasks nor queries.
Rename a mission using the pencil beside its sidebar name. Save name or Enter saves; Cancel or Esc discards. Renaming updates the title without changing the objective or stopping agents.
#Mission triage and attention
Jev also evaluates intent, complexity, risk, ambiguity, internet needs, and read-only limits. Selection considers specialists' configured models and effort. Suggested adjustments do not restart or reconfigure sessions automatically. JEV results in the mission's top bar shows triage and compares observed Jev and local routing outcomes.
Open Local assistant in the top bar, Commands → Open local assistant, or Alt+O for Needs attention: blockers, review deliveries, and recoverable failures, even without Ollama. With Ollama, automatic summaries avoid repeated queries if relevant state is unchanged; Generate summary now refreshes explicitly. See docs/JEV_INTEGRATION.md for limits.
Antigravity variants such as gemini-3.8-flash-high already define reasoning effort. Changing Effort under Add agent chooses an available variant without sending a conflicting --effort.
#Mission status and advanced audit
Progress → Mission status shows recorded team progress, blocked/failed tasks, deliveries awaiting review, and agents awaiting input or unavailable. Actions open the relevant terminal, activity, dependency view, or review. Connection loss is marked as showing the last received data.
Architecture auditing is under Settings → Advanced → Cockpit audit, for developers and maintainers. Alt+C and Open Cockpit audit lead there. Refreshing reads a saved report; it does not run tests.
#Getting started with guidance
Start with guidance offers the included Vibe Coding Toolkit on the home and creation screens: choose your stage, read a guide, and prepare a request to review and send. Guides, prompts, and templates are bundled under MIT at a pinned revision. See Command.
#Team office
Office opens full Habblaud: characters, tasks, feed, history, My day, timelapse, themes, and the online city client. Real panels appear automatically, with Cockpit terminals and messages. Compact view preserves filters and an accessible list. The complete MIT copy is bundled; external hooks require setup, and free World access requires an account/waitlist. See Office.