Skip to content

ENT-14721: Added Policy builder documentation #3815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
aleksandrychev wants to merge 1 commit into
base: master
Choose a base branch
from
+2,123 −0
Draft

ENT-14721: Added Policy builder documentation #3815

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions content/policy-builder/_index.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
layout: default
title: Policy Builder
sorting: 45
---

Policy Builder is a desktop application for writing CFEngine policy without writing the policy language by hand.
You describe the state you want your hosts in, such as a package installed, a file with certain content or a service running, by placing blocks on a canvas and connecting them.
Policy Builder turns them into CFEngine policy, checks it, tests it on containers on your own computer and deploys it to your CFEngine hub.

## How Policy Builder works

You build policy from ready-made pieces, each one thing a host should have or do: install a package, write a file, keep a service running.
You fill in the details, such as which package or what the file contains, put the pieces in the order they should happen, and say which hosts they're for.
Policy Builder writes the CFEngine policy for you, and you can read every line of it, which is also a good way to learn the policy language.

From there, it follows the policy all the way to your hosts:

1. **Build**: assemble the policy in a project, a folder on your computer.
2. **Test**: run it on containers on your own computer, and see what it changed.
3. **Deploy**: send it to your CFEngine hub, where every host fetches it.

[The demo project][] is a complete project to explore, ready to test. See [Promises][] for the CFEngine idea behind each piece.

## The window

![The parts of the Policy Builder window](policy-builder-window-parts.png)

1. **Top bar**: the project's name and settings, and its four views: **Canvas**, where you build; **Generated Policy**, the policy the blocks become; **Tests & Logs**, test runs on containers; **Deployment**, getting the policy to your hub. On the right, **AI agent** and **Save**.
2. **Activity bar**: switches the side bar between **Blocks and files** and **Modules**; **Project settings** at the bottom.
3. **Blocks**: every block, by category, with search. The tag on the right of each block, such as `files`, is the CFEngine promise type it generates.
4. **Configurations**: the project's policy files. Click one to open it on the canvas.
5. **Canvas**: the open configuration's blocks and arrows, numbered in run order, with the zoom, Tidy up and full screen tools at the bottom.
6. **Properties**: the selected block's settings, or the open configuration's when nothing is selected.
7. **Status bar**: what Policy Builder is doing, the project, the open file and its namespace.

Keyboard shortcuts in these pages are written for macOS, with ⌘ (Command), ⇧ (Shift) and ⌥ (Option); on Windows and Linux, use Ctrl for ⌘ and Alt for ⌥.
**Help**, then **Keyboard Shortcuts** lists them all.

## What you need

- **Policy Builder** on your computer: see [Installing Policy Builder][].
- **A CFEngine hub, with hosts bootstrapped to it**, to deploy to: the hub is the policy server your hosts fetch their policy from, and a host joins it by bootstrapping to it when CFEngine is installed. Community and Enterprise hubs both work; see [Installing CFEngine][]. You can build and test policy without one.
- **CFEngine 3.27 or later** on the hub and hosts: the generated policy relies on promises running in the order they're written, which is new in 3.27.
- **CFEngine Enterprise** for Mission Portal and for deploying through a git repository the hub pulls. A Community hub is deployed to over SSH instead.

## In this section

1. [Installing Policy Builder][]
2. [Policy Builder projects][]: what a project is, creating, opening and saving one
3. [Building policy on the canvas][]: blocks, arrows, conditions, groups and configurations
4. [Generated policy][]: what Policy Builder writes, and how to read it
5. [Values and templates][]: variables, classes, lists and data, and templates
6. [Modules in Policy Builder][]: CFEngine Build modules
7. [Test environments][]: running the policy on containers before it reaches real hosts
8. [Deploying from Policy Builder][]: to a hub, through git or over SSH
9. [AI agents in Policy Builder][]: letting an AI agent build with you
10. [The demo project][]: a complete project to explore, using everything above
11. [Block reference][]: every block, its settings and the policy it generates, and [Custom CFEngine and Call Method][] for what no block does
67 changes: 67 additions & 0 deletions content/policy-builder/ai-agents.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
layout: default
title: AI agents in Policy Builder
sorting: 100
---

AI agents such as Claude Code can build and change a project in Policy Builder while you watch.
Policy Builder runs an MCP server, the standard way AI agents use the tools of other applications: through it, an agent adds blocks, connects them, sets variables and conditions, adds modules and runs tests, with every change showing on the canvas as it's made.
The agent uses its own account and model; Policy Builder doesn't send your project anywhere itself.

## Connecting an agent

1. Click **AI agent** in the top bar, or choose **File**, then **Connect AI Agent…**.
2. Turn on **Let AI agents connect**.
3. Pick your **Agent**: Claude Code, Gemini CLI, OpenAI Codex, VS Code (Copilot), Cursor, or another MCP client.
4. Copy what Policy Builder shows and use it as it says: a command to run once in a terminal, or settings to add to the agent's configuration file.

![The Connect an AI agent dialog](policy-builder-connect-agent-dialog.png)

For Claude Code, the command looks like this:

```command
claude mcp add --transport http --scope user cfengine-policy-builder http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"
```

Only programs on your computer that know the token can connect.
Keep Policy Builder open, with the project the agent should work on: the agent works on the open project, and nothing is saved until you or the agent save it.

Then ask the agent in its own window, for example: "In Policy Builder, add a block that installs chrony and keep the chronyd service running after it."

## What an agent can do

An agent can always read the project: its files, blocks, generated policy, variables and test results.
What it may change is set in the same dialog, under **What agents may do**, for every agent at once:

| Permission | Lets an agent |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| **Edit blocks and variables** | Add and change blocks, arrows, groups, entries, transformers and conditions. |
| **Files and folders** | Add, rename and describe policy files and folders. |
| **Create, open and save projects** | Write the project to disk. |
| **Run tests** | Set up test environments and run them in Docker. |
| **Allow deleting** | Remove blocks, arrows, entries, transformer steps, files and test environments. |

What's turned off isn't offered to agents at all.
(_Transformers_ are a variable's transforms, described in [Values and templates][].)
Agents also get a guide to working in Policy Builder, so they use the blocks, check their work and ask you before judgement calls such as a schedule or a looser permission.

## While an agent works

When an agent starts working, a bar at the top of the window says what it's doing, and the editor is locked so the two of you don't edit at the same time.
**Log** opens a panel at the bottom that lists each step the agent took, and how long it took.

![An AI agent at work, with its log open](policy-builder-agent-working.png)

**Stop** stops the agent at once: its next call is refused, and it's told you stopped it. You can add a **Note for the agent**, such as "wrong project", to tell it why.
**Allow again** lets it continue.

## Reviewing an agent's changes

Each change an agent makes is one undo step, so ⌘Z takes back its changes one at a time.
Before saving, read what it built:

- the canvas, and each block's settings in Properties;
- the **Generated Policy** view, for the exact policy;
- **Tests & Logs**, if it ran tests.

The guide asks agents to record their decisions in the note of the block they affect, so check the notes too.
24 changes: 24 additions & 0 deletions content/policy-builder/blocks/_index.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
layout: default
title: Block reference
sorting: 110
# Generated by scripts/docs-blocks.mjs in cfengine/policy-builder, from its block descriptors: edit those, not this page.
---

Every block Policy Builder offers, by category: what it does, its settings, and the CFEngine policy it generates.

| Page | Blocks |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [File blocks][] | [Clean Up Old Files][File blocks#Clean Up Old Files], [Copy Directory][File blocks#Copy Directory], [Copy File][File blocks#Copy File], [Create Directory][File blocks#Create Directory], [Create Symlink][File blocks#Create Symlink], [Create/Edit File][File blocks#Create/Edit File], [Remove Directory][File blocks#Remove Directory], [Remove File][File blocks#Remove File], [Render Template][File blocks#Render Template], [Rotate Log][File blocks#Rotate Log], [Set Permissions][File blocks#Set Permissions], [Watch File for Changes][File blocks#Watch File for Changes] |
| [File content blocks][] | [Comment Out Lines][File content blocks#Comment Out Lines], [Ensure Lines in File][File content blocks#Ensure Lines in File], [Remove Matching Lines][File content blocks#Remove Matching Lines], [Replace Text in File][File content blocks#Replace Text in File], [Set Config Values][File content blocks#Set Config Values] |
| [Variable and class blocks][] | [Define Class][Variable and class blocks#Define Class], [Define Variable][Variable and class blocks#Define Variable] |
| [Package blocks][] | [Install Package][Package blocks#Install Package], [Remove Package][Package blocks#Remove Package] |
| [Command blocks][] | [Cron Job][Command blocks#Cron Job], [Run Command][Command blocks#Run Command] |
| [Service blocks][] | [Manage Service][Service blocks#Manage Service] |
| [User blocks][] | [Manage Users][User blocks#Manage Users] |
| [Storage blocks][] | [Mount Storage][Storage blocks#Mount Storage] |
| [Report blocks][] | [Report Message][Report blocks#Report Message] |
| [Process blocks][] | [Signal Process][Process blocks#Signal Process] |
| [Blocks from modules][] | [Git Checkout][Blocks from modules#Git Checkout], [HTTP Request][Blocks from modules#HTTP Request], [Run Ansible Playbook][Blocks from modules#Run Ansible Playbook], [Systemd Unit][Blocks from modules#Systemd Unit] |
| [Method blocks][] | [Call Method][Method blocks#Call Method], [Custom CFEngine][Method blocks#Custom CFEngine] |
| [Custom CFEngine and Call Method][] | When no block does what you need, policy you write yourself or a bundle that already exists |
Loading
Loading