Cockpit

Cockpit 3.0 One control plane for Flutter development and black-box application E2E.

English · 简体中文

Cockpit is a production application development, E2E automation, and verification stack for AI and CI. Flutter source development uses a first-class managed adapter with structured widget, route, log, error, network, and runtime state. Independently, installed Android and iOS applications can be controlled and verified as non-invasive black boxes. Both paths expose the same typed resources to CLI, MCP, and future clients without conflating their roles.

It provides:

• standalone LON, JSON, or YAML cases and suites;
• semantic, native accessibility, system, visual, and coordinate planes;
• target discovery, registration, launch, inspection, and capability truth;
• dependency DAGs, fixtures, matrices, retries, bounded concurrency, and

fail-fast suites;

• durable run events, restart-safe suite checkpoints, exact session affinity,

cancellation, artifacts, and complete offline regression report bundles;

• a per-user authenticated Supervisor with isolated per-workspace workers;
• resource-oriented CLI, HTTP/SSE API, and MCP clients without a bundled GUI.

Packages

• [cockpit_protocol](packages/cockpit_protocol) owns platform-neutral DTOs,

the test DSL, JSON Schema, and OpenAPI contract.

• [cockpit](packages/cockpit) owns the Supervisor, workspace workers, drivers,

CLI, MCP server, reports, and artifacts.

• [flutter_cockpit](packages/flutter_cockpit) is the first-class in-app

Flutter development and semantic validation adapter. Pure black-box users do not need it.

Minimum versions are Dart 3.8.0 and Flutter 3.32.0. Install the host CLI once:

dart pub global activate cockpit any
cockpit --help

Upgrade the installed runtime with one command:

cockpit update

It installs and verifies the latest release while requiring Pub to resolve a version at least as new as the running executable, so stale package indexes fail safely instead of downgrading Cockpit. It hands a source-installed native executable back to Pub, restores one optimized AOT executable, removes retired and temporary update payloads, and replaces an older running Supervisor while preserving its authorization mode and durable state. Dart Pub owns its shared download cache; Cockpit never deletes unrelated cached packages.

Flutter source development additionally uses the development-only bridge:

dev_dependencies:
  flutter_cockpit: any

Keep Cockpit development-only. Native black-box testing does not require an application source dependency or a Flutter integration. Do not add flutter_cockpit imports to production lib/ code.

Install For AI Agents

The repository-owned Skill and complete host integration guide live at [skills/cockpit](skills/cockpit).

Preferred: ask the current AI host to install the CLI, Skill, native adapter, and MCP surface for you. Copy this prompt:

Install Cockpit for the current AI host, including the CLI, complete cockpit Skill, native adapter, and cockpit_mcp when supported, by following https://github.com/cockpit-dev/cockpit/blob/main/skills/cockpit/INSTALL.md

Complete host-specific installation and verification instructions live in [skills/cockpit/INSTALL.md](skills/cockpit/INSTALL.md). Native adapter and MCP details are documented in the [agent integration guide](docs/agent-integrations.md).

Flutter Fast Path

Run from the intended Flutter project. dev discovers and owns the workspace, target, process, port, and bridge, then reuses that project's active numeric handle while checkout identity keeps concurrent projects isolated:

cockpit dev start cockpit/main.dart --platform macos
cockpit dev status
cockpit dev inspect "Save"
cockpit dev tap "Save"
cockpit dev wait
cockpit dev screenshot
cockpit dev reload
cockpit dev diagnose --verbosity standard

Omit the entrypoint and platform when Cockpit can infer them. Normal commands also omit the current handle, LON format, minimal verbosity, and operation timeout. dev automatically runs its local Supervisor in process-scoped yolo mode; strict policy remains available for black-box, CI, staging, and production workflows. Cockpit does not read a keychain or secret store, and --env values are process-only.

Runtime Model

cockpit commands discover or start one daemon under COCKPIT_HOME. The daemon owns authentication, workspace identity, authorization, admissions, leases, ports, run projections, and artifacts. It starts an isolated worker for each active workspace and engine version. No command relies on a global "latest" project or session.

%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 36, "rankSpacing": 44, "padding": 12}}}%%
flowchart TB
  subgraph ControlPath["cockpit_protocol · typed control plane"]
    direction LR
    Actors["AI agents · developers · CI"]
    Surfaces["Skill · CLI · MCP · REST API"]
    Supervisor["Supervisoridentity · auth · policy · runs"]
    Actors --> Surfaces --> Supervisor
  end

  Workers["Isolated workspace workersA / B / … / N"]
  Router["Capability routerper worker"]
  Flutter["Fluttersemantic · runtime"]
  Native["Mobile black boxADB · WDA"]
  Desktop["Web · desktopbrowser · window"]
  Evidence["State · events · reports · artifacts"]

  Supervisor --> Workers --> Router
  Router --> Flutter & Native & Desktop
  Flutter & Native & Desktop -.-> Evidence

  classDef gateway stroke:#5B8DEF,stroke-width:2px,font-weight:600
  classDef core fill:#345CBA,stroke:#7BA1F2,color:#FFFFFF,stroke-width:2px,font-weight:700
  classDef evidence fill:#247A57,stroke:#4CB782,color:#FFFFFF,stroke-width:2px,font-weight:600
  class Surfaces,Router gateway
  class Supervisor core
  class Evidence evidence

  style ControlPath fill:transparent,stroke:transparent

Register multiple projects once, then address them explicitly or run a command from inside exactly one registered workspace:

cockpit daemon start
cockpit root add --path /work/projects --label projects
cockpit workspace register --root-id  --path /work/projects/app-a
cockpit workspace register --root-id  --path /work/projects/app-b
cockpit workspace list

CLI Output

The default is minimal canonical LON. Omit default output options in normal commands. --verbosity standard|full adds context without changing operation accuracy; --format json|yaml|jsonl|path|none changes output encoding or delivery. Use --verbosity full --output .lon for a complete response. Request JSON only for jq, a JSON-only consumer, or JSON wire inspection. When --output or an artifact command writes a file, stdout contains only its verified path. File bytes, Base64, hashes, and decision-irrelevant byte counts never enter terminal output.

Authorization

Dangerous operations and test safety effects are denied unless explicitly authorized. Persist policy under COCKPIT_HOME/authorization.json; validate and apply it through the CLI. A running daemon must be restarted so one process cannot change authority mid-run.

{
  "schemaVersion": "cockpit.supervisor.authorization/v2",
  "allowedDangerousOperations": [
    "app.launch",
    "app.restart",
    "app.stop",
    "command.batch",
    "command.run",
    "evidence.screenshot.capture",
    "lease.recover",
    "recording.start",
    "recording.stop",
    "system.action",
    "target.launch"
  ],
  "allowedOperationSafetyEffects": [
    "capture",
    "externalSideEffect",
    "permission",
    "recording",
    "reset",
    "system"
  ],
  "allowedTargetEnvironments": [
    "development",
    "test",
    "staging",
    "production"
  ],
  "allowedSafetyEffects": [
    "communication",
    "credentialSensitive",
    "destructive",
    "externalNavigation",
    "financial",
    "permissionChange"
  ]
}

cockpit daemon policy validate --file authorization.json
cockpit daemon policy apply --file authorization.json --restart
cockpit daemon policy show

For an explicitly unrestricted local session, start the Supervisor with cockpit daemon start --yolo (or daemon restart --yolo). YOLO applies only to that daemon process. An unflagged start or restart preserves a healthy running daemon's current mode; when no daemon is running, it starts with the persisted restricted policy. Stop first when an explicit return to restricted mode is required. daemon status, attempt manifests, and suite report.json record the effective auth.

A policy may explicitly authorize production or unknown; the default policy does not. Quarantined leases remain blocked until verified cleanup succeeds. The Supervisor advertises lease.list and the reset-authorized lease.recover operation for exact lease/workspace/resource/holder identities. An explicit forceRelease: true may release an unverified logical resource; forwarded ports always require verified cleanup and can never be force released.

Black-Box Targets

Register an installed application without changing its source:

cockpit target register \
  --workspace-id  \
  --platform android \
  --device-id emulator-5554 \
  --target-kind nativeApp \
  --app-id com.example.app \
  --environment test \
  --mode automation \
  --idempotency-key android-target-001

cockpit target launch --workspace-id  --target-id  \
  --idempotency-key android-launch-001
cockpit target inspect --workspace-id  --target-id 

Android uses ADB and native accessibility. iOS Simulator uses simctl; native iOS UI interaction uses a reachable WebDriverAgent endpoint. Physical iOS installation and lifecycle use devicectl where available. Cockpit reports unsupported or unavailable capabilities instead of claiming control it cannot prove.

For an installed Flutter app or a native app embedding Flutter, register targetKind: flutterApp with an appId and no entrypoint, then author the case on the native plane. Cockpit launches it through system control and drives the complete native accessibility tree without an application dependency. The Flutter-aware resolver locally collapses duplicate ancestor semantics and prefers actionable matches while leaving native screens, platform views, WebViews, and distinct list rows intact. Use an entrypoint-backed Flutter target and the semantic plane only when the optional development bridge is required.

Flutter targets accept a structured launch configuration across CLI, MCP, and op run. Cockpit owns the entrypoint, device, mode, flavor, and remote control flags; callers can supply repeatable dart defines, define files, additional safe Flutter arguments, process environment values, and a launch budget up to 30 minutes:

cockpit target launch \
  --workspace-id  \
  --target-id  \
  --dart-define API_URL=https://api.example.test \
  --dart-define-from-file config/staging.json \
  --env LOG_LEVEL=debug \
  --flutter-arg=--track-widget-creation \
  --timeout 30m \
  --idempotency-key flutter-launch-001

The equivalent operation input uses a launchConfiguration object with dartDefines, dartDefineFromFiles, flutterArgs, and environment. Launch configuration values are not returned in operation output. Do not pass Flutter launch fields to installed black-box targets. On Android and iOS, environment configures the Flutter build process; mobile application processes do not inherit arbitrary host variables. Use Dart defines or an application-owned configuration channel for values the app must read.

Every advertised operation includes executionMode, defaultTimeoutMs, and maximumTimeoutMs. Synchronous operations block until their result and accept one op run --timeout override such as 90s or 20m. Case and suite runs are durable jobs: submission returns a runId immediately, then clients consume events and the terminal report. case run --timeout defaults to 30 minutes and allows up to 6 hours; suite run --timeout defaults to 2 hours and allows up to 24 hours. Step and cleanup timeouts remain independent inner budgets.

Each step may explicitly select semantic, native, visual, or coordinate with plane. Without an override, Cockpit routes screenshot assertions to the visual plane, system and location-travel actions to native control, visual and coordinate locators to their matching planes, and native-only constraints to native accessibility. Other steps inherit the case plane. An entrypoint-backed Flutter session keeps the semantic driver and a secondary system driver for the same app/device, so one case can inspect Widgets and then cross a native screen, platform view, permission dialog, or visual-only surface without changing the application under test. The authoritative secondary capability profile is the sanitized target.inspect operation result at output.systemControl; clients must not reconstruct it from app.get, whose platform app and process identities are intentionally redacted.

The shared action vocabulary includes copyText, eraseText, pasteText, and bounded travel routes in addition to gestures, editing, keyboard, wait, assertion, capture, recording, and system actions. Visual locators use a workspace-confined image file and an optional similarity threshold. assertScreenshot compares a live capture with a workspace-confined baseline and records actual, baseline, and diff images as offline artifacts; image bytes never enter terminal output. Baselines must be selected by a stable visual profile such as platform, device or viewport, pixel ratio, and orientation. A dimension mismatch is a profile mismatch or layout regression; Cockpit does not resize either image to manufacture a comparison.

Cases And Suites

Cases and suites use schemaVersion: cockpit.test/v2. Validate documents before submitting them, and use stable idempotency keys for replay:

cockpit case validate --workspace-id  --file cases/login.yaml
cockpit case run --workspace-id  \
  --document-id  --case-id login \
  --idempotency-key login-2026-07-24 \
  --timeout 30m

cockpit suite validate --workspace-id  --file suites/regression.yaml
cockpit suite run --workspace-id  \
  --document-id  --suite-id regression \
  --idempotency-key regression-2026-07-24
cockpit suite report --run-id  \
  --output-dir cockpit-report

After worker termination, completed nodes stay complete, an active attempt becomes interrupted, and the suite continues only when its retry policy allows it. Persisted fixture and row bindings must resolve to the same healthy session; Cockpit fails explicitly when that session can no longer be proven.

Lifecycle composition uses the smallest existing scope: suite fixtures for campaign or attempt setup/teardown, case setup/finally for case ownership, step evidence for before/after/failure capture policy, and explicit startRecording/stopRecording steps around the exact interval that needs video. if, bounded retry/loop, and fragments compose normally inside these scopes, so a second generic pre/post hook model is unnecessary.

Every finalized suite publishes one portable report bundle. Export it with suite report --output-dir cockpit-report; the CLI downloads only the files declared by the run manifest, verifies their metadata and SHA-256 while downloading, and commits the directory only after the bundle is complete. The destination must not already exist. Open index.html offline to move from release summary and coverage through executions, evidence, diagnostics, and environment/files. Search, filters, deep links, and responsive/print layouts work without a server or network. The sections are task-oriented rather than persona-specific: developers, testers, product owners, and release leads inspect the same facts and evidence chain without role tabs hiding or duplicating information. report.json is the canonical single-file fact graph containing suite and case definitions, attempts, detailed steps,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cockpit-dev
• Source: cockpit-dev/cockpit
• License: MIT

Install and usage instructions live in the source repository linked above.