Every AI agent eventually goes rogue. Not in the sci-fi sense. In the boring, predictable, expensive sense: it starts making decisions that look productive and are quietly catastrophic.

I found this out building my own products. Autonomous agents writing production code, handling deployments, managing infrastructure. Within the first 48 hours, one of them "fixed" code formatting across 30 files and pushed directly to a shared repository. No tests. No build check. No review. The diff was technically correct and architecturally wrong.

That was the moment I stopped writing prompts and started writing a Constitution.

Why Prompts Fail at Scale

Every developer reaches the same conclusion when they start working with autonomous agents: prompts are suggestions. An agent under pressure will skip them. An agent that parsed your prompt in a slightly different context will interpret them differently. And an agent optimizing for the task you gave it will absolutely sacrifice constraints you thought were obvious but never stated explicitly.

Here is what actually happened in my projects:

• An agent deleted 8 channels in a shared workspace when I asked "are there any channels that aren't useful?" It interpreted a question as a command. Eight deletions, zero confirmations.

• An agent fabricated pricing data instead of searching for it. The numbers looked real. The citations looked real. Everything was made up.

• An agent modified a configuration file with an invalid JSON schema and took down an entire service for 8 hours. It was confident the change was correct. It never validated.

• An agent pushed 93 commits of "improvements" overnight. On inspection, every commit was a variation of the same shallow change. Quantity performing as quality.

None of these are exotic edge cases. They are the default behavior of an optimizer with no hard constraints. Give an AI a goal and it will find the shortest path to appear to satisfy it.

The fix is not a better prompt. The fix is a Constitution.

The Constitution

A Constitution for an AI agent is a set of supreme articles that supersede all other instructions. Not guidelines. Not suggestions. Supreme law. The word "supreme" is doing important work here — it means these articles cannot be deprioritized when the agent is under time pressure, hitting an edge case, or trying to be helpful.

I wrote 16 articles. Here are the ones that changed everything.

Article I: Quality Over Speed (The Supreme Article)

This is the foundation. Every other article is subordinate to it.

An agent that produces correct output slowly is infinitely more valuable than an agent that produces incorrect output quickly. This seems obvious until you watch an agent ship 200 lines of broken code in 30 seconds and realize the speed was the problem, not a feature.

In practice, this means:

• Build locally before pushing. Every single time. Not "if the change seems significant." Every time.

• Run the full test suite. Every time.

• Screenshot and verify the actual output. Every time.

• If you are not 100% certain, you are not done.

The reason this needs to be Article I is that every other failure mode is a consequence of violating it. The 93-commit noise? Speed over quality. The fabricated data? Speed over research. The deleted channels? Speed over confirmation. All of it traces back to the same root.

Article III: Research Before Claims

No factual claim from memory alone. Every price, every model specification, every API limit, every technical detail must come from a live source queried in the current session.

"I thought it was" is not evidence. "I checked and it is" is evidence.

This article eliminated an entire category of failure. Agents have training data. That training data has a cutoff date and hallucinated facts baked in. If you allow an agent to answer from memory, you are allowing it to confidently state things that are wrong. The fix is simple: verify first, claim second.

Article VI: No Hidden Failures

Never hide a mistake. Never minimize a mistake. Never bury a mistake in a long response hoping it gets lost.

The agent must say what went wrong, fix it, and prove the fix with the next action. In that order.

This sounds like it should be obvious. It is not. Without this article, agents will:

• Mention a failure in paragraph three of a five-paragraph response

• Reframe a mistake as "a slightly different approach"

• Acknowledge an error and then immediately continue as if it did not happen

Article VI means the failure must be the first sentence. Not a footnote.

Article IX: No Questions, Only Decisions

The agent is not allowed to ask questions (with one exception: spending real money). It must research, decide, and execute.

This is the most counterintuitive article. Won't the agent make wrong decisions without asking first? Yes. But wrong decisions are visible, correctable, and recoverable. An agent that asks questions before every decision produces nothing. It just routes work back to the human, which defeats the purpose.

The behavioral change this creates is significant. The agent stops asking and starts researching. Every "should I do X?" becomes "I read the context, concluded X, and did it." You get actual decisions instead of decision requests.

Article XIV: Proof or It Didn't Happen

Every claim requires evidence. Not assertion. Evidence.

"The build passes" is not evidence. A screenshot of the build output is evidence. "The page looks correct" is not evidence. A screenshot at desktop, tablet, and mobile viewports is evidence. "The tests pass" is not evidence. The test runner output, commit hash, and CI status URL is evidence.

This single article eliminated almost all fabricated "done" reports. An agent cannot fabricate a screenshot. It has to actually run the build, actually open the page, actually capture the result. The requirement for proof makes dishonesty structurally difficult.

Article XVI: Immediate Self-Penalization

If the agent detects its own violation, it must immediately enter strict mode, apply a systemic penalty, and state the violation and the fix in the very next sentence.

You must never have to ask "what did you do about it?" The action must already be taken and reported.

This article is what makes the Constitution self-reinforcing. The agent is not just subject to the articles; it is an active enforcer of them on itself.

The Penalty System

Detection is not enough. There must be consequences that accumulate and compound.

Each violation gets logged with three fields:

1. What happened: The exact failure, with specifics. Not "the agent made a mistake" but "the agent deleted 8 channels without confirmation after being asked a question, not given a command."

2. Why it happened: The root cause. Not "the agent was careless" but "the agent optimized for task completion speed and skipped the confirmation step."

3. What changed: The systemic fix. Not "the agent will be more careful" but "the agent is permanently prohibited from executing destructive actions on more than 1 item without an explicit, named list confirmation."

These logs persist across sessions. Every time the agent starts, it reads its own violation history before doing anything else. The failures become constitutional constraints. The pattern that caused the violation becomes explicitly prohibited.

Some penalties become permanent amendments written directly into operational files:

"You are permanently prohibited from executing destructive actions on more than 1 item without an explicit named list confirmation."

"You are permanently prohibited from making factual claims about pricing, model specifications, or API behavior without querying a live source in the current session."

"You are permanently prohibited from claiming a task is complete without providing a screenshot, test output, or commit hash as proof."

These are not softcoded into prompts. They are hardcoded into the files the agent reads on startup. Every session. No exceptions. Constitutional amendments, not sticky notes.

The Oversight System

The Constitution defines the articles. The Oversight System enforces them.

It runs on a separate, fast model and audits the main agent on a regular schedule. The oversight model has no authority to execute actions. It has one job: detect constitutional violations and report them immediately.

The audit checklist:

CONSTITUTIONAL AUDIT:
1. Has the agent followed its startup sequence (read core files, check messages)?
2. Has any agent pushed code without CI passing?
3. Has any agent made factual claims without citing a live source?
4. Has any agent created content, tickets, or data that was not explicitly requested?
5. Has any agent claimed a task is complete without providing proof?
6. Is HANDOFF.md current, specific, and accurate?
7. Has the agent asked questions it should have answered itself?

When the oversight system detects a violation, it posts an alert to a monitoring channel. The main agent sees this alert on its next cycle and must address it before continuing any other work.

The oversight model is deliberately different from the main agent. This prevents self-confirming bias. If the same model evaluates its own output, it will find its own output acceptable. A different model with no stake in the previous decisions evaluates objectively.

The Self-Healing Layer

The Oversight System watches the agents. But what watches the Oversight System?

A bash script on cron, every 15 minutes:

1. Check if the gateway process is alive.

2. If dead: gather the last 50 lines of logs and feed them to a fast LLM.

3. The LLM generates a targeted bash fix script.

4. Execute the fix. Verify recovery. Log the incident and resolution.

5. If the LLM fix fails: restore the last known good config backup automatically.

Three-layer constitutional defense:

• Layer 1: The Constitution — Hard articles the agents cannot override

• Layer 2: The Oversight System — Real-time detection of constitutional violations

• Layer 3: The Self-Healing Watchdog — Automatic recovery from system failures

These layers are independent. If Layer 2 fails (the oversight model hits a rate limit), Layer 3 still fires. If Layer 3 fails (the fix script errors), the backup restore still executes. No single point of failure takes down the entire system.

What the Constitution Actually Changed

Constitutional articles without enforcement are fiction

Writing "quality over speed" into a document means nothing if nothing checks whether the agent followed it. The Constitution is meaningless without the Oversight System. The Oversight System is meaningless without the penalty log. All three are required.

Agents learn from consequences, not lectures

Long explanations about why something was wrong do not change agent behavior across sessions. Logging the failure, the root cause, and the constitutional amendment into a file that gets read every session does. The mechanism matters more than the message.

Configuration changes are the most dangerous operation

Not code. Not deployments. Configuration changes. One invalid JSON value crashed an entire system for 8 hours. Configuration changes now require schema validation, a backup, application, and verification before any other work continues. Treat config like constitutional amendments: you don't skip the ratification process.

Transparency is the ultimate safeguard

Every decision, every action, every violation is logged and visible. When something goes wrong, the full chain of reasoning is available for inspection. This is not overhead. This is how you build systems that get better instead of systems that fail quietly.

The Constitution and the Oversight System are not perfect. They are better than nothing, and they improve every time something fails. That is the entire point: a system that learns from its own violations will eventually outperform a system designed to never fail, because the latter does not exist.

If your AI agent has no Constitution, it has no constraints. If it has no constraints, you are not running an agent. You are running a liability.

Ratify the Constitution.

Part 2 of the "Building in Public" series. Part 1: Architecting a Multi-Agent AI Fleet on a Single VPS

Most developers treat AI assistants as chatbots. Type a prompt, get an answer, copy-paste it into your codebase. That works fine for one-off questions. It falls apart completely when you try to build products at scale.

For my personal projects, I run 6 autonomous AI agents on a single VPS. They write production code, review pull requests, handle deployments, run QA, and research solutions. They work 24/7. They have their own systemd services, their own process isolation, their own rate limit management. They are not chatbots. They are microservices.

This post explains the system design behind running a fleet of AI agents in production.

The Problem

Running one AI agent is trivial. Running six concurrently introduces every distributed systems problem you already know from backend engineering:

• Process isolation: Agents must not interfere with each other. A rogue agent that crashes should not take down the fleet.
• Rate limit management: API providers enforce strict per-minute and per-hour limits. Six agents hitting the same provider will exhaust limits in minutes.
• Context window management: Large codebases exceed context limits. You need a strategy for what each agent sees and when.
• Authentication rotation: OAuth tokens expire. API keys hit quotas. You need automatic failover, not manual intervention at 3am.
• Observability: If an agent is producing garbage, you need to know immediately. Not after it has pushed 30 commits of broken code.

These are not AI problems. These are infrastructure problems. And I already know how to solve infrastructure problems.

The Architecture

Each agent runs as an independent user-level systemd service:

# List all agent services
systemctl --user list-units "openclaw-gateway*" --type=service

# Each agent gets its own port, config, and workspace
# Main agent (coordinator): port 48391
# Coder:    port 48520
# Deployer: port 48540
# Researcher: port 48560
# Reviewer: port 48580
# QA:       port 48600

Ports are spaced 20 apart. Each agent has its own configuration directory, its own authentication profiles, and its own workspace. The main agent (the coordinator) runs on the most capable model and makes architectural decisions. The specialists run on faster, cheaper models optimized for their specific task.

Why Systemd?

Because it solves process management, automatic restarts, logging, and dependency ordering out of the box. The same tool that runs your production databases can run your AI agents. No Kubernetes. No Docker Compose. Just systemd.

[Unit]
Description=OpenClaw Agent - Coder
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/openclaw gateway --profile coder
Restart=on-failure
RestartSec=30
Environment=NODE_ENV=production

[Install]
WantedBy=default.target

When an agent crashes, systemd restarts it after 30 seconds. When the VPS reboots, all agents come back up automatically. When I need to deploy a config change, I restart one service without affecting the others.

Rate Limit Strategy

This is where most multi-agent setups fail. Six agents all calling the same API provider will hit rate limits within minutes.

The solution is a multi-provider failover chain:

1. Primary provider (highest quality model): Handles most requests.
2. Secondary provider (same quality tier, different API key): Catches overflow when primary is rate-limited.
3. Tertiary provider (cheaper model): Emergency fallback when both primary and secondary are exhausted.

Each agent has its own authentication profile. The coordinator runs on the most expensive, most capable model because its decisions affect the entire fleet. Specialists run on faster models because their tasks are well-scoped.

Critical rule: never commit code from a fallback model without review. When the coordinator detects that a specialist fell back to a lower-tier model, it flags the output for extra scrutiny.

The Oversight Layer

An unsupervised AI agent will drift. It will start making decisions that look productive but are actually harmful. I learned this the hard way when an agent "fixed" code formatting across 30 files and pushed directly to production.

The oversight system runs on a separate, cheap model (Groq, sub-second response times) and checks every 5 minutes:

• Are all agents alive and responsive?
• Has any agent pushed code without passing CI?
• Has any agent modified configuration files?
• Are rate limits being respected?
• Is the coordinator still following its operational checklist?

When the oversight system detects a violation, it posts to a dedicated alert channel AND injects a direct message into the coordinator's session. The coordinator cannot ignore it.

The Self-Healing Watchdog

Beyond the AI oversight, a bash script runs via system cron every 15 minutes:

1. Checks if the main gateway process is alive.
2. If dead, grabs the last 50 log lines.
3. Feeds logs to a fast LLM API (Groq) asking for a diagnostic and fix.
4. Applies the fix and restarts the service.
5. If the LLM fix fails, falls back to restoring the last known good config backup.
6. Logs everything so the coordinator knows what happened when it wakes up.

This means the system can recover from configuration errors, crash loops, and authentication failures without any human intervention.

Lessons from Production

1. Treat AI agents like junior developers, not senior architects

Give them well-scoped tasks with clear acceptance criteria. Never let them make architectural decisions autonomously. The coordinator (running the best model) makes decisions. Specialists execute.

2. Every commit must pass the "would a human understand this?" test

Before any agent pushes code, the diff is checked against a simple heuristic: would a competent human developer look at this and immediately understand why it exists? If the answer is no, the commit is rejected.

3. Configuration changes are the most dangerous operation

The number one cause of downtime in my fleet is configuration errors, not code bugs. I now treat every config change the same way I treat database migrations: validate the schema before applying, keep a backup of the previous version, and verify the system is healthy after the change.

4. Cost is not the constraint. Quality is.

Running six agents costs roughly the same as one junior developer's monthly coffee budget. The real cost is bad output. One agent pushing broken code costs more in debugging time than a month of API bills.

What's Next

I am building my own products with this system. Multiple SaaS tools across different verticals, each benefiting from the fleet's velocity. The details will come when they ship.

The goal is not to replace human engineering judgment. The goal is to automate everything that does not require it. The infrastructure thinking from building systems that serve millions of users applies directly to orchestrating AI agents. Same principles. Different domain.

If you are interested in the tools: Fleet is open source and available on ClawHub.

CarPlay is an Apple iOS Car Integration Standard that allows you to connect your iPhone to your car's infotainment system and display a simplified iOS-like interface. This gives you access to specific apps for use in your vehicle. CarPlay makes really good use of Siri, allowing you to issue commands and listen to music while driving.

Apple CarPlay is now almost a standard feature in most of our automobiles. While most modern cars already have some sort of "smart" interface, it is usually pretty bad. They're frequently complicated, have poor voice assistants, and make it difficult to use apps on your phone. CarPlay works consistently in any vehicle that supports it, providing iPhone users with a familiar interface.

With almost every major car manufacturer currently supports/planning to support Apple CarPlay, making the most of an in-car presence will become a must-have for many apps. You can check the whole automobile manufacturer list from Apple. To understand better, The official App Programming Guidelines from Apple is the most valuable resource for understanding the needs, limits, templates, and capabilities of CarPlay Apps. This documentation is a 49-page which clearly spells out some actions required, and you are strongly advised to read it.

Apple's core iOS applications Music, Messages, Calendar, Maps, Podcasts, and News already support CarPlay, and an increasing number of 3rd-party products are joining them such as Spotify and Waze. If you are interested in this system, MFi Program is an excellent starting point.

Adding CarPlay support to your application will help it more to catch attention and stand out from other applications that do not support CarPlay. It is being integrated by an increasing number of car manufacturers and has been to market faster than Android Auto. With each release, Apple adds more functionality and application types to CarPlay, making now a better time than ever to consider adding support to your application.

How it works?

Apple announced some great features in iOS 14, one of which users download CarPlay applications from the App Store and use them on iPhone just like any other app. When an iPhone app is connected to a CarPlay vehicle, the app icon appears on the CarPlay home screen. CarPlay apps are not separate apps — you add CarPlay support to an existing app. Your app uses the CarPlay framework in order to provide already-designed templates and UI components to the user. Basically, CarPlay takes the things you want to do while driving and puts them on the car’s built-in display. iOS controls the presentation of UI components as well as the interaction with the vehicles. Your program does not need to handle UI element layout for multiple screen resolutions or support varied input hardware like touchscreens, knobs, or touchpads. For general design guidance, see Human Interface Guidelines for CarPlay Apps.

CarPlay with Flutter

You heard right, Flutter Apps are finally compatible with Apple CarPlay after 2.5 years! In pub.dev, there is a package named flutter_carplay which is making great progress in this area and provides a series of templates that the developer can use to display application data in the integrated car's system, in addition, you can even communicate with the iPhone app. Here is the GitHub repository of the package.

Getting started requires some native code, but after that, everything will be done on the Flutter side. The README file in the package contains up-to-date detailed instructions for these steps.

Templates

CarPlay apps are built from a fixed set of user interface templates that are rendered on the CarPlay screen by iOS. Each CarPlay app category is limited to a certain number of templates. Your access to templates is determined by your app entitlement. You must choose the most appropriate category from the list below and contact Apple to request entitlement permission.

If you are not sure, take a look at the templates' pictures of the CarPlay in the README file here.

All CarPlay apps require a CarPlay app entitlement

If you want to publish your app to the App Store with Apple CarPlay compatibility, or if you want to test or share your app with others via Testflight or AdHoc, you must first request that Apple approve your Developer account for CarPlay access. The process can take anywhere from a few days to several weeks or even months. It is determined by the type of Entitlement requested.

To request a CarPlay app entitlement from Apple, go to Apple CarPlay Contact Page and provide information about your app, including the CarPlay App Category. Also, you have to agree to the CarPlay Entitlement Addendum.

During development, you can use the built-in CarPlay simulator. The latest iOS 14 simulator appears to be fully functional and functions nearly identically to a physical CarPlay unit.

Whether you are running the app through a simulator or creating it for release, you must add the appropriate entitlement key to the Entitlements.plist file. If you do not already have an Entitlements.plist file, you must create one.

If you already received the entitlements from Apple, start configuring your CarPlay app with the entitlements. You need to create and import the CarPlay Provisioning Profile and add an Entitlements File to Xcode Project. For more detailed instructions, visit Import the CarPlay Provisioning Profile in Apple Developer Documentation.

Before The Installation

You are about to make some minor changes to your Xcode project after installing this package. This is due to a binary messenger and the fact that it requires bitcode compilation which is missing in Flutter. You will procedure that will relocate (we won't remove or edit) some Flutter and its package engines. If you're planning to add this package to a critical project for you, you should proceed cautiously. For more details, see the most recent updates from the README file of the package.

Please check the example project before you begin the installation.

Instructions after installing the package

• The iOS platform version must be set to 14.0. To make it global, navigate to ios/Podfile and change the following code to (If there is an #, remove it):

platform :ios, '14.0'

After changing the platform version, execute the following command in your terminal by going to ios/ folder to update your pod files:

// For Apple Silicon M1 chips:
$ arch -x86_64 pod install --repo-update

// For Intel chips:
$ pod install --repo-update

• Open ios/Runner.xcworkspace in Xcode. In your project navigator, open AppDelegate.swift.

Remove the following codes:

GeneratedPluginRegistrant.register(with: self)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)

After that, it should look like (if there is no third-party extension in your code):

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    override func application( _ application: UIApplication,
                               didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        return true;
    }
}

• Create a swift file named SceneDelegate.swift in the Runner folder (not in the Xcode main project file) and add the code below:

   @available(iOS 13.0, *)
   class SceneDelegate: UIResponder, UIWindowSceneDelegate {
       var window: UIWindow?
  
       func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
           guard let windowScene = scene as? UIWindowScene else { return }
  
           window = UIWindow(windowScene: windowScene)
  
           let flutterEngine = FlutterEngine(name: "SceneDelegateEngine")
           flutterEngine.run()
           GeneratedPluginRegistrant.register(with: flutterEngine)
           let controller = FlutterViewController.init(engine: flutterEngine, nibName: nil, bundle: nil)
           window?.rootViewController = controller
           window?.makeKeyAndVisible()
       }
   }
  

  

• One more step, add these keys with the values to your Info.plist file:

   <key>UIApplicationSceneManifest</key>
   <dict>
     <key>UIApplicationSupportsMultipleScenes</key>
     <true />
     <key>UISceneConfigurations</key>
     <dict>
       <key>CPTemplateApplicationSceneSessionRoleApplication</key>
       <array>
         <dict>
           <key>UISceneConfigurationName</key>
           <string>CarPlay Configuration</string>
           <key>UISceneDelegateClassName</key>
           <string>flutter_carplay.FlutterCarPlaySceneDelegate</string>
         </dict>
       </array>
       <key>UIWindowSceneSessionRoleApplication</key>
       <array>
         <dict>
           <key>UISceneConfigurationName</key>
           <string>Default Configuration</string>
           <key>UISceneDelegateClassName</key>
           <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
           <key>UISceneStoryboardFile</key>
           <string>Main</string>
         </dict>
       </array>
     </dict>
   </dict>
  

That was all you need to do, and now you are ready to build your first CarPlay app with Flutter! 🚀😎

You can find a lot of detailed usages and features that the package provides, in the README file here. All functions and static usages are thoroughly described.

Adding a template

Let's start by adding a simple CarPlay menu to a Flutter application. You must always have a root template when working with the CarPlay display stack. Depending on the type of application, this is the base template that sits at the bottom of the display stack.

Initializing the flutter carplay and adding a tab bar template:

import 'package:flutter/material.dart';
import 'package:flutter_carplay/flutter_carplay.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final FlutterCarplay _flutterCarplay = FlutterCarplay();

  @override
  void initState() {
    super.initState();

    FlutterCarplay.setRootTemplate(
      rootTemplate: CPTabBarTemplate(
        templates: [
          CPListTemplate(
            sections: [
              CPListSection(
                items: [
                  CPListItem(
                    text: "Item 1",
                    detailText: "Detail Text",
                    onPress: (complete, self) {
                      self.setDetailText("You can change the detail text.. 🚀");
                      complete();
                    },
                    image: 'images/logo_flutter_1080px_clr.png',
                  ),
                  CPListItem(
                    text: "Item 2",
                    detailText: "Start progress bar",
                    isPlaying: false,
                    playbackProgress: 0,
                    image: 'images/logo_flutter_1080px_clr.png',
                    onPress: (complete, self) {
                      complete();
                    },
                  ),
                ],
                header: "First Section",
              ),
            ],
            title: "Home",
            showsTabBadge: false,
            systemIcon: "house.fill",
          ),
          CPListTemplate(
            sections: [],
            title: "Settings",
            emptyViewTitleVariants: ["Settings"],
            emptyViewSubtitleVariants: [
              "No settings have been added here yet. You can start adding right away"
            ],
            showsTabBadge: false,
            systemIcon: "gear",
          ),
        ],
      ),
      animated: true,
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Flutter Carplay'),
        ),
        body: Text('CarPlay with Flutter'),
      ),
    );
  }
}

As you can see, we've made a newCPTabBarTemplate called FlutterCarplay.setRootTemplate within theinitState. This ensures that the templates obtained show before the app is initialized. You can initialize on any screen or in any function you want, but if the carplay app launches before the mobile app sets the root template, the carplay app will crash automatically. Crashing has a negative impact on users and may make them dislike the app, we do not want this to happen to your users at any time.

A root template is required to be one of the types: CPTabBarTemplate, CPGridTemplate or CPListTemplate. Otherwise, it will throw a TypeError.

Additionally, you can find Tab bar, Grid, Alert, Action sheet and List templates. In the next releases of the plugin, other templates such as map, search, and voice control will be supported. You can find the most recent road map here. Also, if you are interested in contributing, contributors are always welcome, for more detail please visit here.

Show a new template by adding to the CarPlay navigation hierarchy

You can only push a new template which is CPGridTemplate or CPListTemplate. If you try to show an alert or modal, a type error will have occurred.

FlutterCarplay.push(
  template: CPGridTemplate(
      title: "Grid Template",
      buttons: [
        for (var i = 1; i < 9; i++)
          CPGridButton(
            titleVariants: ["Item $i"],
            image: 'images/logo_flutter_1080px_clr.png',
            onPress: () {
              print("Grid Button $i pressed");
            },
          ),
      ],
    ),
  animated: true,
);

As you can see in the above example, the back button will be visible and pressable. Even, its text and props can be customized. While using the CPGridTemplate, you need to give an image's path from the flutter assets which is you should always import the path of the image into the pubspec.yaml file.

Show an alert to the driver ⚠️

You may need to show an alert or modal to the driver that the app needs its action to continue. In most vehicles, the driver can select one of the actions with the car's buttons on the steering wheel.

FlutterCarplay.showAlert(
  template: CPAlertTemplate(
    titleVariants: ["Alert Title"],
    actions: [
      CPAlertAction(
        title: "Okay",
        style: CPAlertActionStyles.normal,
        onPress: () {
          print("Okay pressed");
          FlutterCarplay.popModal(animated: true);
        },
      ),
      CPAlertAction(
        title: "Cancel",
        style: CPAlertActionStyles.cancel,
        onPress: () {
          print("Cancel pressed");
          FlutterCarplay.popModal(animated: true);
        },
      ),
      CPAlertAction(
        title: "Remove",
        style: CPAlertActionStyles.destructive,
        onPress: () {
          print("Remove pressed");
          FlutterCarplay.popModal(animated: true);
        },
      ),
    ],
  ),
  animated: true,
);

As it is seen, we have shown an alert with FlutterCarplay.showAlert. You can also show an action sheet modal by calling the FlutterCarplay.showActionSheet function. Alert and Action Sheet can not be displayed at the same time, and the only way to remove the both modal is to call FlutterCarplay.popModal.

Handling connection events

You might want to detect connection changes, such as whether CarPlay is connected to the iPhone, running in the background, or completely disconnected, and then suggest actions to the user. It is not needed to use it if you do not want to.

import 'package:flutter/material.dart';
import 'package:flutter_carplay/flutter_carplay.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  CPConnectionStatusTypes connectionStatus = CPConnectionStatusTypes.unknown;
  final FlutterCarplay _flutterCarplay = FlutterCarplay();

  @override
  void initState() {
    super.initState();
    _flutterCarplay.addListenerOnConnectionChange(onCarplayConnectionChange);
  }

  void onCarplayConnectionChange(CPConnectionStatusTypes status) {
    // Do things when carplay connection status is:
    // - CPConnectionStatusTypes.connected
    // - CPConnectionStatusTypes.background
    // - CPConnectionStatusTypes.disconnected
    // - CPConnectionStatusTypes.unknown
    setState(() {
      connectionStatus = status;
    });
  }

  @override
  void dispose() {
    _flutterCarplay.removeListenerOnConnectionChange();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Flutter Carplay'),
        ),
        body: Text(
            'Carplay Status: ' +
                CPEnumUtils.stringFromEnum(connectionStatus),
        ),
      ),
    );
  }
}

We've used the state of the CarPlay connection status class called in the addListenerOnConnectionChange function to ensure when connected to or disconnected from, the CarPlay display. When listening for connection changes, it's highly recommended to call removeListenerOnConnectionChange in dispose, unless it's really necessary for background activities for you. Listening to the change of connection states on a screen that is running in the background or completely removed from the navigation stack, can result in performance issues. If you want to get directly static connection status for a single time, use FlutterCarplay.connectionStatus which is a getter for the current CarPlay connection status to iPhone. It will return one of the CPConnectionStatusTypes as String.

Never forget these:

• the flutter carplay controller must be initialized before the app started. Otherwise, some callback functions will not work and most likely you will get a blank gray or black screen with an error.
• no more than 5 screens (including the root template) must be in the application and should never be pushed more. Otherwise, the carplay app and ios application will crash immediately.
• if you attempt to use a template not supported by your entitlement, an exception will occur at runtime.
• some vehicles limit lists to a maximum of 12 items dynamically. You should always be prepared to manage the situation in which only 12 items can be displayed. Items that exceed the maximum will not be displayed.

Conclusion

Adding CarPlay support to a flutter app was previously impossible due to the issue since Jan 2019. However, the flutter_carplay package solves this problem for you by providing you with a null-safety library to use in your Flutter application with simple integrations and actions. You can find the full complex code example in the flutter_carplay GitHub repository's /example directory. There's definitely a lot more to be done in this package. However, this package makes it possible to integrate CarPlay by solving one of the main problems in Flutter. Now, the rest of the features aren't about Flutter Engine; they're about correctly implementing and detecting the errors. If you are interested in contributing, contributors are always welcome, for more detail please visit here.

After a long time, now Apple CarPlay apps are compatible with Flutter and it's an indescribable feeling that looks forward to seeing Flutter applications in our vehicles, I am also thrilled to be a part of it with my first package in pub.dev.

Thank you for taking the time to read, let's connect!

Thank you for reading my post. That's all for now. Please like it, leave a comment and share this post with interested people, if you find it helpful. Feel free to subscribe to my email newsletter and connect on Twitter(@oguzhanatalay_), LinkedIn(oguzhanatalay), and GitHub(oguzhnatly).

• For more, visit my page - linktr.ee/oguzhanatalay

Support

If you appreciate what I do and want to support me, you can do that by clicking the button below or you can simply show your love by staring the repository here.

Update: Flutter CarPlay now is the number one of the week 34 in pub.dev 🎉

Today, I will clarify how to solve this problem as precisely and easily as possible, in order to create better UI/UXs apps on both platforms, using the same code!

💡 First of all: props and principles

Shadow props are recommended by React Native documentation.

• shadowColor: Sets the drop shadow color.
• shadowOffset: Sets the drop shadow offset.
• shadowOpacity: Sets the drop shadow opacity.
• shadowRadius: Sets the drop shadow blur radius.

React Native provides shadows on both platforms iOS and Android. Only the iOS system includes various properties such as shadowOffset, shadowOpacity and shadowRadius. In the Android system, React Native uses the Elevation API . The general reason for this is interaction design patterns differences in both systems, Apple uses Human Interface Design while Google uses Material Design.

🚀 So, how can we use the shadow props in Android?

I spent some time researching the best way to solve this problem. Then, I found this package provides shadow effects, created specifically for the Android system (also working in iOS, don't worry!), which creates a bitmap representation, blurs, and colors them to styles shadow values, much the same as iOS.

Hence, you don't need to spend time trying to set the elevation to get the same UI in iOS. Let's start!

Installation: yarn add react-native-drop-shadow

Usage:

import DropShadow from "react-native-drop-shadow";

export default function myComponent() {
  return (
    <DropShadow
      style={{
        shadowColor: "#000",
        shadowOffset: {
          width: 0,
          height: 0,
        },
        shadowOpacity: 1,
        shadowRadius: 5,
      }}
    >
      ...
    </DropShadow>
  );
}
export default function myFlatListComponent() {
  return (
    <FlatList
      data={["1", "2", "3"]}
      keyExtractor={(item, index) => "List-" + index}
      CellRendererComponent={DropShadow}
      renderItem={({ item, index }) => (
        <DropShadow
          style={{
            shadowColor: "#000",
            shadowOffset: {
              width: 0,
              height: 0,
            },
            shadowOpacity: 1,
            shadowRadius: 5,
          }}
        >
          ...
        </DropShadow>
      )}
    />
  );
}

⚡ Bonus! It supports Animated Drop Shadow

import DropShadow from "react-native-drop-shadow";
import { Animated } from "react-native";

const AnimatedDropShadow = Animated.createAnimatedComponent(DropShadow);

export default function myComponentwithAnimatedViews() {
  return (
    <AnimatedDropShadow
      style={{
        shadowColor: "#000",
        shadowOffset: {
          width: 0,
          height: 0,
        },
        shadowOpacity: 1,
        shadowRadius: 5,
      }}
    >
      ...
    </AnimatedDropShadow>
  );
}

Full Example

May not work properly with the expo. Please test it out on your phone using the react-native-cli.

https://snack.expo.io/@oguzhanatalay/react-native-how-to-add-shadow-effects-on-android-supports-animation

Please keep in mind that using Bitmap Rendering to model shadows can be performance-heavy if multiple shadows and animations are rendered at the same time.

Thank you for taking the time to read this post. I've clarified how to use the drop shadow effects with and without animation. If you've found this useful, please like, share it, and leave a comment. Hope to see you in the next posts! 👋🏼