Skip to content
Back to search

cuga-agent

CUGA is an open-source generalist agent harness for the enterprise, supporting complex task execution on web and APIs, OpenAPI/MCP integrations, composable architecture, reasoning modes, and policy-aware features.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cuga-project/cuga-agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cuga-project/cuga-agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cuga-project--cuga-agent/badge.svg)](/listings/cuga-project--cuga-agent)

HTML

<a href="/listings/cuga-project--cuga-agent"><img src="/api/listings/cuga-project--cuga-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Switch to hybrid mode:**

   # Edit ./src/cuga/settings.toml and change:
   mode = 'hybrid'  # under [advanced_features] section

2. **Install browser API support:**

- Installs playwright browser API and Chromium browser - The `playwright` installer should already be included after installing with [Quick Start](#quick-start)

   playwright install chromium

3. **Start the demo:**

   cuga start demo

4. **Enable the browser extension:**

- Click the extension puzzle icon in your browser - Toggle the CUGA extension to activate it - This will open the CUGA side panel

5. **Open the test application:**

- Navigate to: [Sales app](https://samimarreed.github.io/sales/)

6. **Try the hybrid task:**

   get top account by revenue from digital sales then add it to current page

**What you'll see:** CUGA will fetch data from the Digital Sales API and then interact with the web page to add the account information directly to the current page - demonstrating seamless API-to-web workflow integration!

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 283 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(max-width: 640px)" srcset="docs/images/readme/hero-mobile.svg">
  4. <img src="docs/images/readme/hero.svg" alt="CUGA — Enterprise automation. Under your control. Sovereign deployment, execution policies, and efficient inference." width="100%">
  5. </picture>
  6. </p>
  7. # CUGA
  8. **The enterprise agent harness for sovereign, policy-controlled automation.**
  9. CUGA turns business requests into actions across your applications, APIs, and documents. Deploy in your private cloud or prepare an air-gapped environment, enforce fine-grained execution policies, and use open models on infrastructure you control. Connect your tools, configure your workflows, and optimize inference for your workload.
  10. **[Get started](#quick-install)** · **[Documentation](https://docs.cuga.dev)** · **[Python SDK](#build-with-the-python-sdk)** · **[Deploy on Kubernetes](deployment/README.md)**
  11. **[CUGA Apps](https://github.com/cuga-project/cuga-apps)** · **[CUGA Harness Kit](https://github.com/cuga-project/cuga-harness-kit)** · **[Discord](https://discord.gg/PN3Zdq4dEd)**
  12. [Apache 2.0](LICENSE) · Configurable Generalist Agent · Built with IBM SiL
  13. English · [简体中文](docs/readme/README.zh-CN.md)
  14. ---
  15. ## Quick install
  16. Use **Python 3.12** and [uv](https://docs.astral.sh/uv/getting-started/installation/).
  17. ```bash
  18. git clone https://github.com/cuga-project/cuga-agent.git
  19. cd cuga-agent
  20. uv sync --python 3.12
  21. test -f .env || cp .env.example .env
  22. ```
  23. <a id="llm-configuration---advanced-options"></a>
  24. Set your provider, model, and credentials in `.env`. See [model configuration](docs/readme/configuration-guide.md#supported-platforms) for supported providers.
  25. ```bash
  26. uv run cuga start manager --crm
  27. ```
  28. Open `/manage` at the local URL printed by the CLI. Try the CRM tools, configure policies, and test a draft before publishing. [More source and demo options](#develop-from-source).
  29. Prefer to try it in your browser first? [Open the quickstart notebook in Colab](https://colab.research.google.com/github/cuga-project/cuga-agent/blob/main/docs/examples/colab/try_cuga.ipynb).
  30. ## Automate enterprise work. Keep control.
  31. | Your priority | What CUGA gives you |
  32. | --- | --- |
  33. | **Sovereignty** | Run the harness in your environment. Connect privately hosted models and tools. Preload supporting model artifacts for disconnected deployments. |
  34. | **Execution policies** | Block disallowed intents, require approval for selected tools, guide workflows with playbooks, and configure tool-level guards. |
  35. | **Inference efficiency** | Choose open models, tune reasoning modes, shortlist relevant tools, set tool-call budgets, and inspect token usage with per-run receipts. |
  36. | **Faster delivery** | Connect MCP servers, OpenAPI services, and Python tools. Configure and test an agent in the UI before publishing a version. |
  37. | **Recurring automation** | Use the separate events service to run agents on schedules, webhooks, and application events, with run history in Events Studio. |
  38. | **Reusable experience** | Load task-specific skills and use a configured Evolve integration to retrieve relevant guidance and user preferences. |
  39. ## See what you can build
  40. Configure tools and policies beside a draft chat, then publish a version for users.
  41. ![Current CUGA manager UI showing connected CRM and Workspace tools, three policies, draft chat, and Publish](docs/images/readme/manager.jpg)
  42. *Current UI, captured from this repository with illustrative Revenue Operations configuration data. Internal endpoints and version labels are examples.*
  43. | Set approval policies | Manage specialized agents |
  44. | --- | --- |
  45. | ![Tool Approval configuration requiring human approval for CRM account updates](docs/images/readme/policies.jpg) | ![Agent dashboard with Revenue Operations, Knowledge Assistant, and Operations Supervisor examples](docs/images/readme/agents.jpg) |
  46. | Choose which tools need approval and show the proposed code before execution. | Configure individual agents and supervisors for different business workflows. |
  47. ### Watch the product tour
  48. https://github.com/user-attachments/assets/2c51ab34-cb7a-43f8-aa1d-9a4cf8e27b5c
  49. *Visual tour of the current UI with sample configuration, flows, run history, and memory records. It does not show a live agent run. [Media details](docs/readme/media.md).*
  50. ## From a business request to a completed workflow
  51. | Workflow | What an agent can do with the right tools and policies |
  52. | --- | --- |
  53. | **Revenue operations** | Match a contact list against CRM, join account data, calculate revenue percentiles, and draft a report. Gate account updates with Tool Approval. |
  54. | **Knowledge assistance** | Search company documents, answer with citations, and combine shared reference material with documents uploaded to a conversation. |
  55. | **Cross-application operations** | Use CugaSupervisor to coordinate specialized agents, each with its own tools and instructions, and prepare results for review. |
  56. | **Browser and API automation** | Combine structured API calls with browser interactions for workflows spanning services and web interfaces. |
  57. | **Recurring operations** | Schedule a weekday report or react to a new document through the events service, then deliver the result to a configured channel. |
  58. Start with the [CRM demo](#develop-from-source), the [knowledge walkthrough](docs/examples/knowledge_demo/README.md), or the [multi-agent examples](docs/readme/configuration-guide.md#cugasupervisor-multi-agent).
  59. ### Build agents around your team's expertise
  60. | Capability | What it enables |
  61. | --- | --- |
  62. | **Multi-agent coordination** | Give specialists focused tools and instructions, then route work through [CugaSupervisor](https://docs.cuga.dev/docs/build/cuga-supervisor/). |
  63. | **Knowledge with citations** | Combine shared company documents with conversation uploads and inspect cited sources. [Knowledge walkthrough](docs/examples/knowledge_demo/README.md). |
  64. | **Reusable agent skills** | Package procedures in `SKILL.md` files and load the relevant instructions when a task needs them. [Skills guide](docs/readme/configuration-guide.md#agent-skills). |
  65. | **Execution visibility** | Record trajectories with `tracker_enabled=true`, inspect them with `cuga viz`, and enable per-run receipts for token usage, model calls, tool calls, and elapsed time. [Run receipts](docs/readme/configuration-guide.md#run-receipt). |
  66. | **Access control** | Configure OIDC sign-in and enable separate chat and management role checks. [Authentication setup](docs/readme/configuration-guide.md#authentication-and-access-control). |
  67. ## Develop from source
  68. <details>
  69. <summary>Clone the repository and run with uv</summary>
  70. Use **Python 3.12** and [uv](https://docs.astral.sh/uv/getting-started/installation/). [uv manages the project environment automatically](https://docs.astral.sh/uv/guides/projects/#running-commands), so you can run commands with `uv run` without creating or activating an environment manually.
  71. ```bash
  72. git clone https://github.com/cuga-project/cuga-agent.git
  73. cd cuga-agent
  74. uv sync --python 3.12
  75. test -f .env || cp .env.example .env
  76. ```
  77. Edit `.env` to choose a model provider and set its credentials. For an OpenAI endpoint:
  78. ```dotenv
  79. AGENT_SETTING_CONFIG=settings.openai.toml
  80. OPENAI_API_KEY=your-api-key
  81. MODEL_NAME=your-model-name
  82. ```
  83. ```bash
  84. uv run cuga start demo_crm --read-only
  85. ```
  86. Open the local URL printed by the CLI. Try:
  87. > from contacts.txt show me which users belong to the crm system
  88. For the configuration UI, open `/manage` on the same server. Connect tools, configure policies, test a draft, and **Publish** when it is ready.
  89. | Next step | Command or guide |
  90. | --- | --- |
  91. | Start the manager with CRM tools | `uv run cuga start manager --crm` |
  92. | Try document-based assistance | `uv run cuga start demo_knowledge` |
  93. | Try supervisor orchestration | `uv run cuga start demo_supervisor` |
  94. | Inspect execution trajectories | `DYNACONF_ADVANCED_FEATURES__TRACKER_ENABLED=true uv run cuga start demo`, then `uv run cuga viz` |
  95. | Configure another model provider | [Model configuration](docs/readme/configuration-guide.md#supported-platforms) · [Environment example](.env.example) |
  96. ### Use your own inference endpoint
  97. Point the OpenAI-compatible configuration at your private inference service:
  98. ```dotenv
  99. AGENT_SETTING_CONFIG=settings.openai.toml
  100. OPENAI_BASE_URL=http://your-inference-service:8000/v1
  101. OPENAI_API_KEY=your-endpoint-key
  102. MODEL_NAME=your-served-model-name
  103. ```
  104. Use the model identifier exposed by your server. Hosted providers and private endpoints share the same harness; model capability, task complexity, and your configuration determine accuracy and inference spending.
  105. </details>
  106. ## Apply guardrails before action
  107. Require approval before updating a CRM account. Configure a ToolGuard to block a booking that exceeds the customer's membership limits. CUGA combines request policies, tool-level enforcement, and human approval so teams can define where an agent may act.
  108. CUGA includes five policy types, configurable through the UI or Python SDK.
  109. | Policy | Purpose |
  110. | --- | --- |
  111. | **Intent Guard** | Block or respond to requests matching configured intent rules. |
  112. | **Playbook** | Supply a standard process for a matching task. |
  113. | **Tool Approval** | Pause selected tool execution for human approval. |
  114. | **Tool Guide** | Add domain instructions; attach ToolGuard code to enforce configured rules before a tool executes. |
  115. | **Output Formatter** | Shape responses to match a configured output format. |
  116. An active ToolGuard checks the applicable app/tool call before the underlying tool runs. A blocked call returns a policy violation without calling that tool. Guard enforcement requires an applicable, enabled guard; instructions alone do not create this execution check.
  117. Combine these with sandbox isolation, tool selection, and execution budgets. Intent matching and natural-language guidance depend on their configuration; use tool guards and approval gates where execution needs explicit control.
  118. **[Policies SDK](https://docs.cuga.dev/docs/build/policies/)** · **[Tool guards](src/cuga/backend/cuga_graph/policy/tool_guard/README.md)** · **[Sandbox configuration](docs/readme/configuration-guide.md#configurations)**
  119. ## Automate work when events happen
  120. Turn a recurring request into a standing workflow: prepare a weekday report, summarize a newly uploaded document, or respond to a configured application event. The events service supports schedules, polling, and push triggers, with delivery to configured channels such as web chat and Slack.
  121. Events Studio brings watchers, agents, and run history into one view. Inspect the trigger, tools, status, and captured output for a run.
  122. ![Current Events Studio showing sample scheduled and document-triggered workflows with illustrative run history](docs/images/readme/events.jpg)
  123. *Current UI with sample workflows and run statuses. No flow was executed or message delivered for this capture.*
  124. The events service is deployed separately beside CUGA. Studio appears when that service is reachable; connectors and delivery channels require their own configuration. See the [events deployment guide](events/deploy/README.md) and [connector setup](events/deploy/ENV.md).
  125. ## Reuse experience with memory
  126. With Evolve configured, CUGA retrieves relevant task guidance and user preferences, then saves configured conversation trajectories for future use. Teams can inspect what the agent remembers, where it came from, and when it was used.
  127. ![Current memory workspace showing sample task guidance, preferences, source conversations, and usage details](docs/images/readme/memory.jpg)
  128. *Current UI with illustrative memory records, source links, and usage counts. These records were supplied as sample data.*
  129. Memory controls let users enable or disable memory and forget records. Administrator settings include retention policies, schedules, and activity views when the backend supports them. Memory requires an enabled service, a stable service-instance identity, and a configured Evolve backend; durable retention requires PostgreSQL and the bundled Evolve HTTP service.
  130. **[Evolve setup](docs/readme/configuration-guide.md#optional-use-evolve-with-cuga)** · **[Memory retention controls](docs/readme/media.md#memory-retention-controls)** · **[ALTK-Evolve](https://github.com/AgentToolkit/altk-evolve)**
  131. ## Deploy within your boundaries
  132. | Deployment | Setup |
  133. | --- | --- |
  134. | **Local or private cloud** | Run the CLI or SDK against your chosen model endpoint and internal tools. |
  135. | **Kubernetes** | Use the [Helm chart and deployment scripts](deployment/README.md), your image registry, and Kubernetes secrets. |
  136. | **Air-gapped environment** | Build and transfer dependencies, images, and supporting model artifacts ahead of time. Use local inference, embeddings, tools, and observability endpoints. The [UBI image](Dockerfile.ubi) includes a [model preloader](src/scripts/preload_models.py). |
  137. Sovereignty covers the entire deployment: configure each model provider, connector, and optional service to stay inside your boundary. The air-gapped image preloads supporting models; deploy the reasoning model and its inference server separately.
  138. ## Strong benchmark foundations
  139. **AppWorld · IBM CUGA + GLM-5.3-Flash**
  140. | AppWorld evaluation set | Task Goal Completion | Scenario Goal Completion |
  141. | --- | --- | --- |
  142. | **Test-Normal** | **93.5%** | **91.1%** |
  143. | **Test-Challenge** | **92.8%** | **84.2%** |
  144. **WebArena: 61.7%** overall success. [Published result](https://arxiv.org/html/2510.23856v1).
  145. ### Measure efficiency on your workload
  146. Use open models and tune the harness to balance quality, latency, and inference spending. Enable a run receipt to inspect the tokens, model calls, tool calls, and time used by an SDK invocation:
  147. ```toml
  148. # settings.toml
  149. [advanced_features]
  150. run_receipt = true
  151. ```
  152. ```python
  153. result = await agent.invoke("Prepare an account revenue report")
  154. print(result.receipt)
  155. ```
  156. Receipts report usage and timing. Calculate cost using your own provider rates or hosting costs. See [run receipts](docs/readme/configuration-guide.md#run-receipt), [reasoning profiles](docs/readme/configuration-guide.md#reasoning-profiles), and [tool shortlisting](docs/readme/configuration-guide.md#strategies).
  157. ## Build with the Python SDK
  158. Add your tools and invoke an agent from your application:
  159. ```python
  160. import asyncio
  161. from cuga import CugaAgent
  162. from langchain_core.tools import tool
  163. @tool
  164. def get_account_revenue(account_id: str) -> dict:
  165. """Return account revenue from a sample data source."""
  166. return {"account_id": account_id, "revenue": 250000}
  167. async def main():
  168. agent = CugaAgent(tools=[get_account_revenue])
  169. result = await agent.invoke("What is the revenue for account acc_01?")
  170. print(result.answer)
  171. asyncio.run(main())
  172. ```
  173. Configure a model before running the example. Replace the sample tool with your own service integration.
  174. **[CugaAgent SDK](https://docs.cuga.dev/docs/build/cuga-agent/)** · **[CugaSupervisor](https://docs.cuga.dev/docs/build/cuga-supervisor/)** · **[Tool integration examples](docs/examples/cuga_with_runtime_tools/README.md)** · **[Durable conversations](docs/readme/configuration-guide.md#sdk-durable-conversations)**
  175. ## Explore further
  176. | Topic | Guide |
  177. | --- | --- |
  178. | Models, execution modes, and testing | [Configuration and development guide](docs/readme/configuration-guide.md) |
  179. | Task-specific instruction packs | [Agent skills](docs/readme/configuration-guide.md#agent-skills) |
  180. | Memory and guidance from previous runs | [Evolve integration](docs/readme/configuration-guide.md#optional-use-evolve-with-cuga) |
  181. | Agent-level and session-level knowledge | [Knowledge demo](docs/examples/knowledge_demo/README.md) |
  182. | MCP and OpenAPI integration | [Tool registry](src/cuga/backend/tools_env/registry/README.md) |
  183. | Expose CUGA to other agents | [CUGA as MCP](docs/examples/cuga_as_mcp/README.md) · [A2A example](docs/examples/a2a_two_cuga/README.md) · [ACP over stdio](docs/examples/acp_stdio/README.md) |
  184. | Event-driven automation | [Events service](events/deploy/README.md) — deployed as a separate service beside CUGA |
  185. | Low-code workflows | [Langflow example](docs/examples/langflow/) |
  186. ## Build with us
  187. Share an enterprise use case, report an issue, or contribute an integration.
  188. **[Open an issue](https://github.com/cuga-project/cuga-agent/issues/new/choose)** · **[Contributing](CONTRIBUTING.md)** · **[Contributors](https://github.com/cuga-project/cuga-agent/graphs/contributors)**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.