cloudagent-console

# Quick Start From a checked-out copy of the repository, install dependencies and start CloudAgent Console: ```bash npm install npm start ``` # CloudAgent Console CloudAgent Console is an open source desktop console for organizing cloud context and running AI agents against cloud environments.  It brings workload documentation, diagrams, dashboards, skills, MCP, governance, and multi-agent execution into one local workspace, with support for the native CloudAgent runner, **Codex CLI**, **Cursor Agent**, and **Claude Code**. CloudAgent Console is early-stage. Contributions are welcome for new cloud providers, data sources, scanner integrations, agent runtimes, workflows, documentation, and platform improvements. ## Why This Project? AI agents are only as useful as the context they have. Without shared cloud context, every session starts cold: architecture notes are pasted manually, resources are rediscovered repeatedly, and important relationships, cost signals, health issues, or compliance state can still be missed. CloudAgent Console keeps that context available. It discovers accounts and workloads, maps resource relationships, generates diagrams, and collects cost, health, threat, compliance, scanner, and agent-run data into a persistent local workspace. ## Design Principles - **Runs locally:** the console, workspace, MCP server, and optional agent CLIs run on your machine. - **Your keys, your providers:** model inference uses your API keys, and cloud discovery uses your existing cloud credentials. - **Guardrailed access:** agents access approved context on demand, with scoped permissions and run history. - **Agent agnostic:** use CloudAgent, Codex CLI, Claude Code, Cursor Agent, or any MCP-compatible client. ## Use Cases <table> <tr> <td width="25%"> <img src="docs/assets/workload-diagram.png" alt="Workload Diagram Example" width="100%" /> <br /> <strong>Workload diagrams</strong> </td> <td width="25%"> <img src="docs/assets/cost-dashboard.png" alt="Cost Dashboard" width="100%" /> <br /> <strong>Dashboards and insights</strong> </td> <td width="25%"> <img src="docs/assets/command-center.png" alt="Command Center" width="100%" /> <br /> <strong>Command center</strong> </td> <td width="25%"> <img src="docs/assets/agent-codex-example.png" alt="Agent Running Example" width="100%" /> <br /> <strong>Agent runs and history</strong> </td> </tr> </table> With CloudAgent Console, you can: - **Document cloud workloads:** discover accounts and workloads, maintain architecture context, generate diagrams, and keep operational notes close to the cloud resources they describe. - **Centralize cloud data for agents:** collect cost, health, threat, inventory, scanner, workload, diagram, and agent-run artifacts in one local workspace. - **Run and track agents through the desktop UI:** create CloudAgent skills, refine them with AI, run them with supported agents, compare results across runtimes, and review run history and artifacts. - **Use CloudAgent Console as an MCP context server:** expose approved workload, environment, and cloud data through the local MCP server so compatible agents and tools can access structured cloud context. - **Investigate cloud signals:** use collected cost, health, threat, inventory, and scanner data to support cloud analysis and operational workflows. - **Build repeatable cloud operations:** create skills and workflows that can evolve into repeatable cloud operations and agent-assisted runbooks. - **Apply governance and security controls:** organize access controls, approval workflows, audit logs, guardrails, and policy enforcement around agent-assisted cloud operations. ## Supported Cloud Environments Current support: - AWS Planned support: - Azure - Google Cloud - GitHub - GitLab ## Supported Agent Runtimes CloudAgent Console includes the native CloudAgent runner and can hand off skill runs to supported local coding-agent CLIs when they are installed and configured. Supported runtimes: - CloudAgent native runner, backed by OpenAI and the OpenAI Agents SDK. - Codex CLI. - Cursor Agent. - Claude Code. Install optional agent CLIs separately, then set their paths in **Preferences**. CloudAgent Console can run without every optional runtime installed; unavailable tools simply will not be used. ## How It Works CloudAgent Console can be used in two main ways. ### Use The Desktop Console You can use the desktop application as the main operating surface. From the UI, you can configure cloud environments, discover accounts and workloads, review dashboards and insights, document architecture context, manage diagrams and notes, create and run CloudAgent skills, configure agent runtimes, and inspect artifacts from agent runs. ### Use The Local MCP Server You can also use CloudAgent Console as a local MCP context server. In this mode, compatible agents and tools running on your system can use the MCP server to access approved cloud environment data in a structured way. This lets external agents retrieve workload context, environment metadata, documentation, diagrams, scanner output, and other cloud artifacts without each agent needing to rediscover or rebuild that context independently. The desktop console and MCP server both use the same local workspace, so cloud context can be organized once and reused across the UI, CloudAgent skills, and compatible local agent tools. ## Local Data Workspace CloudAgent Console stores preferences, cloud context, workload documentation, diagrams, scanner output, and agent-run artifacts in a local workspace. Optional integrations can extend where context comes from and which agent runtimes are used, but the core console is designed to run from a local desktop environment. ## Roadmap Planned areas of work include: - Repeatable workflows for cloud operations and agent-assisted runbooks. - Broader Azure and Google Cloud support. - GitHub and GitLab context integrations. - More scanner, inventory, cost, health, threat, and compliance data sources. - More flexible MCP and agent-runtime attachment points. - A hardened packaged installer flow for public desktop downloads. ## Desktop Development Targets CloudAgent Console currently supports source/development use on: - macOS - Windows Packaging configuration currently targets macOS and Windows. Linux packaging is not a current target. ## Requirements Required for running CloudAgent Console from source: - **OpenAI API key** for CloudAgent, skill generation, and AI-assisted analysis. - **Node.js `20.19.0` or newer** and npm. - **AWS environment** to onboard if you want account discovery, scans, workload documentation, and cloud insights. - **AWS CLI** installed and configured if you want to use AWS discovery and related cloud operations. ## Install And Getting Started ### Install From Source CloudAgent Console does not yet provide a hardened public desktop installer. For now, run it from a checked-out source repository. For a checked-out copy of the repository, run the local setup script from the repository root: ```bash npm run setup:local ``` The setup script installs npm dependencies, builds the desktop UI, and starts the local Electron app. It is a source-checkout bootstrap script, not the final downloadable desktop installer. To install dependencies without launching the app: ```bash npm run setup:local -- --no-launch ``` To start the app without reinstalling dependencies: ```bash npm run setup:local -- --skip-install ``` After setup, you can also start the built local app directly with: ```bash npm start ``` ### First-Run Setup 1. Open **Preferences**. 2. Add your OpenAI provider key and model. 3. Confirm the local data directory. 4. Enable or disable the local MCP server. 5. Configure optional CLI paths for AWS CLI, Codex CLI, Cursor Agent, and Claude Code. 6. Open **Cloud Setup** and add an AWS environment. 7. Run account discovery to inventory accounts and discover workloads. CloudAgent Console persists these settings locally. Environment variables are developer overrides, not required setup. ### Onboard An AWS Account 1. Confirm your AWS CLI profile works outside CloudAgent Console. 2. Open **Cloud Setup**. 3. Add the AWS account or organization details. 4. Run discovery. 5. Review discovered accounts and workloads under **Workloads**. ## How To Contribute Useful contributions include: - Bug reports with clear reproduction steps. - Documentation improvements for setup, cloud onboarding, MCP, skills, dashboards, and workflows. - New cloud providers, developer platforms, data sources, scanner integrations, or agent-runtime integrations. - Focused pull requests that keep changes scoped to one feature or fix. Before opening a pull request, run the relevant local checks for the area you changed. For UI or desktop changes, start with: ```bash npm --workspace @cloudagent/desktop-ui run build ``` ## Project Documentation - [Changelog](CHANGELOG.md) - [Desktop app architecture and packaging](cloudagent-desktop/README.md) - [MCP server and tools](core/mcp/README.md) - [Skills: building, creating, and managing skills](core/skills/README.md) - [Managing cloud environments and workloads](core/workloads/README.md) - [Dashboards and insights: cost, health, and threat](cloudagent-desktop/apps/ui/README.md) - [Scanners and data collection](core/scanners/README.md) - [Supported agent runtimes](core/agent-runtime/README.md) - [CloudAgent orchestration](core/cloudagent/README.md) - [Workflows](core/workflows/README.md)