Skip to content
BranchesTags

Repository files navigation

Citadel — Fortress, Keep, Prism for macOS

Citadel

Citadel is your macOS command center for network control and local AI.

Fortress watches every connection. Keep runs your agents inside the walls.

You stay in charge — on your Mac, on your terms.

English · Français · Changelog · Release guide · Attributions · Feedback


Share Citadel

Your network guardian. Your agents. One menu bar.


Table of contents

TOC


Citadel — Fortress Activity with live 3D network map


👋🏻 Getting Started & Join Our Community

Citadel is a macOS menu-bar app that combines a native application firewall, a full AI agent workspace, and a glass-dark design system — built for people who want visibility and control without giving up modern agent tooling.

Fortress watches the network. Keep is where local and cloud AI agents help with files, code, and chores — privately on your Mac. Prism is the shell that ties it together: ambient canvas, menubar presence, and a desk companion when you want one.

Whether you are hardening a work machine or running agents on-device, Citadel is designed to be open, inspectable, and yours. The project is under active development; feedback and issues are welcome.
Star the repo — follow releases and roadmap updates on GitHub.
Open an issue — bugs, feature requests, and feedback.

Important

Star us on GitHub to get notified on every release — no delay ~ ⭐️



✨ Features

Most security tools and AI clients live in separate worlds. Firewalls block without context. Agent apps chat without seeing what is on the wire. You end up alt-tabbing between System Settings, terminal proxies, and half a dozen chat windows — with no shared picture of what your Mac is doing.

Citadel changes that.

Citadel treats network visibility and agent work as one surface: Fortress enforces policy, Keep runs the agents, and Prism keeps the experience calm. Humans and agents share the same walls.

Fortress: Your Network Guardian

Live telemetry, explainable suspects, and rules you can reason about — from the menubar to a 2D/3D flow map.

  • Activity — process families, site breakdown, live map, one-click allow/deny
  • Suspects — hard local signals only: unsigned apps, first-seen destinations, sensitive ports
  • History — persisted connections, filters, CSV export
  • Rules — domains, IPs/CIDR, process identity (name, bundle ID, Team ID), blocklists, expiry
  • DNS over HTTPS — local DNS proxy with blocklist integration
  • Per-app filter — Network System Extension for process-level enforcement
  • Menubar & Crest — protection status, mode picker, recover UI when the icon is hidden

Fortress Activity — stream detail with allow/deny actions

Fortress Suspects — explainable alerts for sensitive ports and new destinations


Keep: Agents Inside the Walls

Your agents run inside Citadel — local models, cloud BYOK, MCP tools, teams, and schedules — all guarded by Fortress network policy.

  • Local models — Ollama, LM Studio, native MLX (on-device via mlx-swift)
  • Cloud BYOK — OpenAI, Anthropic, Gemini, xAI, OpenRouter, OpenAI-compatible endpoints
  • Agent CLIs — Claude Code, Codex, Gemini, Goose, Cursor, Copilot, and more via ACP
  • MCP & skills — configure servers, OAuth, PDF/Mermaid/cron/office automation, and more
  • Sessions & teams — history, fork, search, multi-agent orchestration, cron schedules
  • Workspace — folder picker, attachments, file preview, voice scribe
  • Permission modes — standard, auto-edits, full auto, plan-only

Keep Ask — local models, MCP, skills, and workspace tools

Keep Agents — orchestrate Claude Code, Codex, Gemini, and other CLIs


Prism: Interface That Gets Out of the Way

A dark glass design system built for long sessions: ambient canvas, readable typography, and optional delight without noise.

  • LivingCanvas — animated background with palette extraction from your wallpaper
  • Prism glass — surfaces, popovers, and sheets with consistent depth
  • Desk Companion — optional floating ambient panel
  • Localization — English and French in-app; adjustable font scaling

Prism shell — Assistants grid with glass-dark surfaces


Trust: Privacy by Architecture

Citadel is built for the Mac you actually use — not a remote dashboard.

  • On-device first — connection history and rules live locally (SQLite + app group)
  • Transparent suspects — every signal is explainable; no opaque ML scoring
  • Agent traffic guarded — Keep inherits Fortress policy; same walls for apps and agents
  • Open components — Swift UI + helper + NetExt; CoworkCore backend from AionCore (Apache-2.0)

Fortress Rules — suggestions from live activity and rule inspector

✨ More features ship as Citadel evolves. See CHANGELOG.


📥 Install Citadel

Citadel ships as a signed macOS app (.app / .dmg). Build from source for development; use a release build for daily use.

Tip

Maintainer packaging, notarization, and Developer ID signing are documented in RELEASE.md.

A Download the latest release

  1. Open Releases and download the latest Citadel.dmg.
  2. Drag Citadel to Applications.
  3. Launch from Applications or Spotlight — Citadel lives in the menu bar (no Dock icon by default).
  4. Complete first-run permissions for full protection.
Step Action
1 Download Citadel.dmg from Releases
2 Open the DMG and drag Citadel to Applications
3 Launch Citadel and approve helper + network filter when prompted

Note

Requirements: macOS 14.0+ on Apple Silicon (arm64). Map view and main app target require macOS 14+. See requirements below.


B Build from source

Quick debug build:

git clone https://github.com/cyberesia/citadel.git
cd citadel
./Scripts/build-debug.sh

Manual build:

./Scripts/prepare-coworkcore.sh   # bundles CoworkCore from AionCore; SKIP_COWORKCORE=1 to skip
xcodegen generate
xcodebuild -scheme Citadel -configuration Debug -derivedDataPath build build
open build/Build/Products/Debug/Citadel.app

Full build with Network Extension (requires Apple Developer signing):

xcodebuild -scheme CitadelFull -configuration Release -derivedDataPath build build

Demo UI (synthetic Fortress traffic):

CITADEL_FORTRESS_DEMO=1 open build/Build/Products/Debug/Citadel.app

Requirements

Requirement Notes
macOS 14.0+ Main app target; map requires 14+
Apple Silicon arm64-only main target
Xcode 15+ Swift 5.10, SwiftUI + AppKit
XcodeGen brew install xcodegen
Apple Developer account Required for CitadelFull / embedded NetExt in production

First-run permissions

For full Fortress protection, approve the privileged helper and network filter in System Settings.

Step Where
1 Allow Citadel login item / helper System Settings → General → Login Items & Extensions
2 Allow network filter / system extension Privacy & Security → Network Extensions
3 Confirm Protection active in Citadel Fortress status / menubar

What works when

Component Without approval With helper + NetExt approved
Activity / map / Suspects Yes (local observation) Yes
Allow/deny remembered May be limited Enforced per-app via NetExt
DNS blocklists Needs helper Yes
Connection history Yes (on-device) Yes
Keep agents Yes (agent traffic follows Fortress when active) Yes

Environment variables

Useful flags for development and CI:

Variable Required Description Example
NO_RUN No Build only; do not launch the app NO_RUN=1 ./Scripts/build-debug.sh
SKIP_COWORKCORE No Skip AionCore download/build SKIP_COWORKCORE=1
CITADEL_DEMO No Enable demo data (app state) CITADEL_DEMO=1
CITADEL_FORTRESS_DEMO No Synthetic Fortress traffic CITADEL_FORTRESS_DEMO=1
COWORKCORE_LOCAL_BINARY No Use a local CoworkCore binary /path/to/aioncore


📦 Ecosystem

Citadel integrates with the local AI and macOS security stack — not a walled garden.

Component Repository Role in Citadel
CoworkCore iOfficeAI/AionCore Agent backend (HTTP/WebSocket); Apache-2.0
MLX Swift ml-explore/mlx-swift On-device inference
mlx-swift-lm ml-explore/mlx-swift-lm LLM loading & generation
swift-transformers huggingface/swift-transformers Tokenizers
Network Extension Apple Per-app NEFilterDataProvider
Prism UI Citadel Sources/CitadelDesign/ Glass design system (Cleanshot-inspired patterns)
PureSnitch momenbasel/puresnitch Early firewall architecture inspiration (MIT); Citadel helper/DNS/pf/netext code rewritten — see Attributions 
flowchart TB
  subgraph App["Citadel.app"]
    F[Fortress UI]
    K[Keep UI]
    P[Prism shell]
  end
  H[CitadelHelper<br/>DNS · pfctl · monitor]
  N[CitadelNetExt<br/>per-process filter]
  C[CoworkCore<br/>AionCore]
  M[MLX / Ollama / BYOK]

  App <-->|XPC| H
  App <-->|App Group| N
  K <-->|HTTP/WS| C
  K --> M
  F --> H
  F --> N
Loading


🧩 MCP, Skills & Agent CLIs

Keep extends through MCP servers, bundled skills, and agent CLI integrations — the same extension model as modern agent harnesses, running behind Fortress.

  • MCP — configure servers, OAuth, and scan agent configs from the Tools panel
  • Skills — PDF, Mermaid, cron, office automation, remote agent setup, and more
  • Agent CLIs — Claude Code, Codex, Gemini, Goose, Hermes, OpenClaw, Cursor, Copilot, … via ACP
  • Channels — chat platform bridges and remote access (pairing plugins)

Keep Tools — Teams, MCP, Schedule, and Agents in one shell

Note

Upstream skill and MCP identifiers are mapped to Citadel-facing copy in Sources/Shared/CoworkUserFacing.swift. Backend IDs stay compatible with AionCore.


⌨️ Local Development

Clone and build on an Apple Silicon Mac with Xcode 15+.

git clone https://github.com/cyberesia/citadel.git
cd citadel
brew install xcodegen
./Scripts/build-debug.sh

Run tests:

xcodebuild -scheme Citadel -configuration Debug -derivedDataPath build test

Project layout:

Sources/
├── CitadelDesign/   # Prism UI, map, LivingCanvas
├── Fortress/        # Activity, Suspects, History, telemetry
├── GUI/             # Shell, menubar, settings, Keep views
├── Shared/          # Models, RuleStore, Cowork client, help catalogs
├── CoworkMLX/       # Native MLX OpenAI-compatible server
├── Helper/          # Privileged daemon
└── NetExt/          # Network system extension

Scripts/             # build, package, notarize, coworkcore prep
Tests/               # Firewall rule evaluator tests

Schemes:

Scheme Use
Citadel Day-to-day debug (app + helper + tests)
CitadelFull Release build with embedded NetExt

See RELEASE.md for Developer ID signing, DMG packaging, and notarization.


🤝 Contributing

Contributions of all kinds are welcome — code, docs, issues, and design feedback.

Tip

Before opening a PR, run tests and ensure ./Scripts/build-debug.sh succeeds on macOS 14+ arm64.

  • Contributing guide — setup, PR expectations, license
  • Security — report vulnerabilities privately
  • Issues — bugs and feature requests
  • Pull requests — code changes
  • In-app guides — Fortress and Keep help catalogs (EN/FR) in Sources/Shared/


❤️ Sponsor

Citadel is open source. If Fortress and Keep make your Mac safer and your agents more useful, here is the best way to give back:

Use the cloud. Fund the walls.

The strongest sponsorship is not a one-off tip — it is to subscribe to and use Aisance Cloud or Cyclones Cloud. Same team behind Citadel; two Swiss AI platforms that extend what you started locally — Aisance Cloud for everyday life and learning, Cyclones Cloud (cyclones.cloud) as the live business showcase.

Citadel holds the perimeter. The cloud expands the playbook.

Platform What you learn & do How it pairs with Citadel
Aisance Cloud Campus flashcards, quizzes, mind maps, and tutors; Camille for admin; Finance; Cosmos chat; Imagine for visuals — structured skills for families and teams Guard agents on-device with Fortress; bring cloud models into Keep via BYOK; delegate everyday work to specialized assistants
Cyclones Cloud Cyberesia’s business showcase on cyclones.cloud: Genesis coworkers, Orbit workflows, Veloce, Plume, and multi-app missions across email, browser, and social — see automation in production Start with local agents in Keep; graduate to full cloud orchestration when you are ready to wire business tools together

Together they cover the full arc: protect on-device → learn with Campus → automate with Genesis → create with Imagine and Plume. A week of real use teaches more than months of scattered AI tab-hopping.

Try Aisance Cloud Try Cyclones Cloud

Star the repo too — it helps others discover Citadel.


🔗 Related Projects

  • AionCore — upstream agent backend (Apache-2.0)
  • AionUi — reference UI for agent workspaces
  • PureSnitch — early Fortress helper/DNS/pfctl/NetExt inspiration (MIT); not bundled; Citadel implementation rewritten
  • mlx-swift — Apple Silicon ML framework for Swift
  • XcodeGen — generate Citadel.xcodeproj from project.yml


📝 License

Copyright © 2026 Citadel contributors.

Licensed under Apache License 2.0 with additional obligations. You may modify and redistribute the software, but must preserve Citadel, Fortress, and Keep wherever they appear here, keep the official logo and branding assets, retain upstream branding/naming updates, and include NOTICES.md, ATTRIBUTIONS.md, and CHANGELOG.md.

Third-party notices and inspiration credits: NOTICES.md · ATTRIBUTIONS.md


About

No description, website, or topics provided.

Resources

Readme
License

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages