English | 日本語 | 한국어 | 繁體中文 | 简体中文
Cuttlely
Open-source agent platform · Apache-2.0
Cuttlely is open-source, context-aware agent orchestration: you build AI agent teams visually, and each agent gets only the context it needs, so you see what every run uses and costs before you publish. Replay real questions on Live and a draft, side by side, before anything changes.
npx cuttlely start
Node 20+ and Docker
Open-source agent platform for lean AI agent teams.
Drag-and-drop agents with real governance and lean context. Open source, Apache-2.0. Cuttlely (said like "cuddly") runs on infrastructure you control: every change waits in a draft, you replay real questions on Live and the draft side by side before you publish, and each specialist gets only the task it needs.
Get started in 10 minutes · Star on GitHub · Already have flows? Bring them over
1.4.7 is out. If you're on 1.4.6, upgrade: Add User now lets you pick an existing user, or enter their email, and adds that account to the team with the chosen role instead of failing with "A user with this email already exists". Their other teams are kept and no second account is created. Adding someone who is already on the team says so, and new users are still created as before. A Harness Specialist's Handoff limit now accepts -1 for no limit, so Harness Prime reads the whole answer (a full context still shortens it). In 1.4.6, with Return Source Documents on, the Retriever Tool now puts a numbered [n] line before each chunk it shows the model, with the chunk's title and its http(s) URL when the metadata has them ([n] title - url), so a harness specialist can cite the page it read. An absolute file path in the metadata shows as the file name only. Harness Prime's Sources: list also adds a source's http(s) URL next to its name when the name is not already that URL. With the option off, the tool's output is unchanged. Start a new session (formerly Clear chat history) now clears the chat on screen and starts a new session; past messages are kept. Pull image 1.4.7 or run npm i [email protected]. In 1.4.5, the PostgreSQL MCP read-only check started accepting read-only string-body SQL and PL/pgSQL helpers that pass the user function rule without an Allowed functions entry. In 1.4.4, changing a model no longer makes MCP calls fail with Unauthorized until a restart. Upgrading from 1.4.2 or earlier? Read the 1.4.3 upgrade notes first. Changelog
Contents
Watch a team resolve a complaint
A customer writes in about a late order. A customer specialist reads the account, an operations specialist finds that the parcel never left the warehouse, and a policy specialist checks the written policy once operations is done, each with its own data and tools. Harness Prime writes the decision, the reply and the actions, with the evidence. Try the demo opens this team on your own model key.
Replay every change before it goes live
Every edit saves to a draft while Live keeps serving your app. Compare, in the Publish dialog, asks real questions on Live and on the draft and marks each answer Same, Changed, or Error before you publish. Turn on the passing test set and Publish waits until the draft passes. Test with up to 100 question-and-answer pairs, with more on the roadmap.
A/B test a change with Compare walks through it. Drafts, tests, and version history lists what else is covered.
Drafts, tests, and version history
- Drafts never touch Live. On chatflows, agentflows, harnesses, and pipelines the canvas saves to a draft. The API, embeds, shared links, schedules, webhooks, a harness's external runs route, and a pipeline's scheduled runs keep serving Live until you publish. The canvas test chat runs your draft, including a harness canvas chat and Try it. Preview on a pipeline runs the draft and does not write to the store.
- Compare before you publish. Recent questions run on Live and on the draft, and each answer is marked Same, Changed, or Error.
- Real answers become tests. Add one answer with Add to test set, or thumbs-up or thumbs-down answers from a time window, up to 500 new rows at a time.
- Score the draft. Text, JSON, numeric and model evaluators give Pass, Fail or Error and a pass rate for Live and the draft. Evaluations
- Publish waits for a pass. The Passing test set gate is off until you turn it on, for a chatflow or an agentflow that starts from chat. Once on, Publish stays disabled until the current draft passes.
cuttlely check --gate runs the same check in CI.
- Every version is kept. Open an old version as your draft or roll Live back in one step, and promote from Dev to Prod, which goes Live only when its owner selects Promote to Live.
- Chatflows, agentflows, harnesses and pipelines keep each saved version, with what changed and who changed it.
- Dev and Prod connect to the same GitHub repository. Prod lists what Dev published, shows what would change and which credentials it needs, and can run the same side-by-side check. Each server keeps its own credentials; only their names travel.
The gate covers Publish of the current draft only. Roll back Live, Promote from Dev, and PUT /api/v1/chatflows/:id still change Live: see which.
On a chatflow, an agentflow, or a harness, the Publish dialog can replay recent questions (4, 10, 25, 50, or 100; 4 is selected first), once on Live and once on your draft, and show both answers side by side with the tokens and time each one took. Choose questions hand-picks stored questions instead, still up to that admin cap. Save as dataset keeps the ticked questions, with blank expected answers to fill in on Datasets. An agentflow that starts from a form, a webhook, or a schedule replays that many recorded inputs instead. A pipeline lists what changed and does not run that check. The check never changes Live or your draft and leaves nothing in chat history. A flow with steps that post or write for real is skipped unless you choose to run it anyway. On a chatflow or a chat-started agentflow, under Questions from, choose A dataset, pick the evaluators, and turn on the passing test set. A harness can score a dataset for that run only, and a form, webhook, or schedule start cannot. Admin > Server Settings > Testing and Limits turns the Publish check on or off. That switch applies on the next check and does not change Publish.
Version history guide · Check recent questions before you publish · Move a flow from Dev to Prod
Made for real teams
Roles, separate teams, sign-in and an audit log, on a server you run.
- Roles and permissions. Teams, the built-in roles, and the permission key for each page and route.
- Sign in. Create the first account. A team can sign in with local users (
CUTTLELY_LOCAL_USERS) and no AuthKit. AuthKit can be turned on later, and a verified email links to an existing local user.
- Users without AuthKit. Local users, invite and reset links, the built-in Owner, Admin, Builder, and Viewer roles, and sessions. An invited person joins only through their own one-time invite link, with or without AuthKit: Invite people.
- Audit log. Sign-in, lockout, invite, reset, role change, user disable, and settings changes.
- Server settings. Change sign-in, the database, storage and more from Admin. Agent runtime > Limits > Agent run time sets the specialist wait: four minutes by default, 300 seconds for five minutes, or 0 for unlimited; save and restart to apply. A shorter Turn time limit still applies. Runtime settings apply without a restart: Testing and Limits, security limits, invite and reset expiry, the SMTP host, port, secure flag, and user,
SENDER_EMAIL, invite delivery, the settings-history cap, and CUTTLELY_AUDIT_RETENTION_DAYS. Env-only values, including secrets, PORT, the data folder, and the SMTP password, show only Set or Not set. The list is Startup options.
Agent teams that power your apps
Give your app a team instead of a single prompt. An agent team is a lead agent with specialists. In Cuttlely, an agent team is called a harness. The lead, Harness Prime, reads the question, splits it into parts, sends each part to the right specialist, and writes one answer. Each specialist can have its own model, tools, playbooks and data. A chatflow calls the whole team by name, so your app, a share link or a website embed can reach it. Your app sends the team a question through the API and gets back one researched answer, a chart or an action. Harnesses guide
- The Analyst is a specialist with its own database. It creates tables, adds rows and answers questions about them with the real numbers, and it never reads Cuttlely's own tables. Long results come back in pages. A harness can have several analysts, each with its own database, and Harness Prime sends each question to the one that fits. Turn it on with
CUTTLELY_ANALYST=auto. Analyst guide
Use a team from your app
Put the team behind a chatflow with one Harness card, publish it, and give it a key from API Keys. On that key, tick the harness under Harnesses this key may run: a new key runs no harness, and the call answers 403 until it is ticked. Your app sends a question and gets the team's answer back. Here is a real call to a small bakery team with two specialists, baker and orders:
curl -s http://localhost:43117/api/v1/prediction/<chatflow-id> \
-H "Authorization: Bearer $CUTTLELY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "How much are two croissants and a sourdough loaf, and can I pick them up on Monday?"}' \
| jq '{text, agents: [.agents[] | {name, task}]}'
{
"text": "Two croissants and a sourdough loaf cost $14.00. However, you cannot pick them up on Monday because the bakery is closed; pick up is possible Tuesday to Sunday from 7:00 to 15:00.",
"agents": [
{
"name": "baker",
"task": "How much are two croissants and a sourdough loaf?"
},
{
"name": "orders",
"task": "Can I pick up two croissants and a sourdough loaf on Monday?"
}
]
}
Harness Prime split the question: baker priced the order and orders checked the pickup day. The full response also has the tokens, the timings, the sources and any images the team made. The API guide covers the rest: API keys, streaming, conversation memory, file uploads, errors, and a runnable example web app that keeps your key on your server. For a long turn, the same key can start the run in the background with POST /api/v1/harnesses/<name>/runs/async and fetch the answer later, and a harness can also run on a cron schedule: Run it from your app with an API key, Run it on a schedule. Reference: Prediction API for harnesses and Call the harness from a chatflow.
Every flow an MCP server.
Other agents can call your Live flow over MCP. Your edits wait in a draft until you publish, and side-by-side replay shows what changed first.
- Off until you turn it on. Turn on MCP Server for a flow to get a Streamable HTTP endpoint (
/api/v1/mcp/<flow id>) and a bearer token.
- Live or published flows only, each flow is one tool call. Calls run the published version, never the draft, and a call keeps no memory of earlier calls. The flow's Rate Limit applies, and request bodies over 1 MB are refused.
- MCP clients via mcp-remote. A client that starts MCP servers as local commands connects with
npx mcp-remote $CUTTLELY_URL/api/v1/mcp/<flow id> --header "Authorization: Bearer <MCP token>". Connect with mcp-remote
MCP endpoint reference
Call a flow from IBM watsonx Orchestrate
Register a published chatflow as an external agent, and an Orchestrate native agent hands it questions as a collaborator. The flow needs a bound API key; a flow without one is refused. A documented path also imports a flow as a remote MCP toolkit. Call a chatflow from Orchestrate · Use a chatflow as an Orchestrate toolkit
Small context, big answers
Long chats, big tables and long rule books don't have to mean long prompts. Each agent sees only what its job needs, and every run shows the tokens it used.
- Each specialist gets its own job. A common pattern hands every agent the whole chat. Harness Prime writes each specialist a task that stands on its own, with a short recap of the recent turns.
- Data stays in the database. A common pattern pastes query results into the prompt. The analyst hands back one page of rows. Say "show more" for the next page. Earlier pages stay out of the next prompt.
- Only the tables you tick. A common pattern pastes the whole database schema into the prompt. On a database connected by URL, tick tables and views in Tables and views on the PostgreSQL MCP node, and the analyst's prompt gets one line for each, with its column names. A
describe tool returns one table's columns, keys and sample text values when the analyst needs them. In our internal benchmarks, on a made-up bakery database, ticking 6 of 20 tables and views took the analyst's prompt from 2,562 to 663 tokens. Rerun it with scripts/analyst-schema-tokens.mjs. A Rules box under the list holds your own instructions for that analyst, up to 2,000 characters, such as which view answers which question. Rules guide the model; they cannot widen the ticked tables or allow writes. Write your own rules.
- Rules load when they're needed. A common pattern puts every instruction in one giant system prompt. Long rules go in playbooks. A specialist opens one only when a question needs it.
- Short handoffs. A common pattern pastes whole documents into the prompt that writes the final answer. Harness Prime reads a capped part of each specialist's answer, with the source names and a short snippet. The documents go back to your app in the response.
- See every token. The run card shows input and output tokens, cached tokens when the model reports them, and the time each step took. The API response carries the same numbers. The Publish check shows Live and the draft side by side with the tokens and time each one used.
How Cuttlely keeps context small
Tools your teams use
Knowledge pipelines (ETL): answers from your own data
Load files, a CSV or a code repository, clean and split them, embed them and store them for search. A run only embeds what changed, can run on a schedule, and local embeddings work with no provider key. Teams and chatflows search the result with the ETL Retriever. ETL guide
Chatflows: one assistant you can ship
A chat model, the agent or chain that answers, memory and tools, on one canvas. Each chatflow gets a prediction API, an embed for your website and a shareable link, and a chatflow with a Harness card puts a whole team behind them. Canvas guide
Agentflows: step-by-step workflows
Workflows that run step by step and can start from a chat message, a form, a webhook or a schedule. Selecting a card opens its settings in a side panel. Canvas guide
Built in everywhere
- Build with AI on every canvas. Describe a team, an assistant, a pipeline or a workflow, and a first version lands on the canvas. Every part and connection is checked first. The building model is one of your own credentials. Build a team, a chatflow, a pipeline
- An agent runtime in the box. Specialists run in an agent runtime that ships with Cuttlely and starts with it, on the same server. There is nothing extra to install or host. Harnesses guide
Your first 10 minutes
New to agents? You do not need to write code. Describe a team with Build with AI and a first version lands on the canvas with starter questions. Ask them in the test chat, and the run card shows which specialists did the work. When it answers well, the chatflow that calls the team gives you a link to share and an embed for your website, so other people can chat with it too.
You need Docker and one model key. The steps use OpenAI. Any chat model provider listed under Credentials works the same way.
-
Get Cuttlely and start it:
git clone https://github.com/cuttlely/cuttlely.git
cd cuttlely
docker compose up -d
Compose pulls the published Cuttlely image. If it cannot pull it, Compose builds the image from your checkout instead, which takes several minutes the first time, and each long build step says which of four it is. docker compose ps shows (health: starting) until Cuttlely is ready, then (healthy). Opening http://localhost:43117 early shows a Cuttlely is starting page that opens Cuttlely by itself.
With Node 20+ and Docker you can skip the clone: npx cuttlely start pulls the image and runs it:
npx cuttlely start
That pulls ghcr.io/cuttlely/cuttlely and opens http://localhost:43117 when it is ready. Install with npm has stop, status, logs and upgrade.
No Docker? Build from source with Node 24 (.nvmrc pins 24.15.0). Native macOS and Windows source installs cannot save or compile agent profiles. Run Cuttlely with Docker there.
-
When it is up, the server prints a ready block with a one-time setup link and a setup code. Show it with:
docker compose logs cuttlely | grep "Setup code"
Started with npx cuttlely start? Run npx cuttlely logs instead. Times in the server log, including the setup code expiry, are in UTC.
Nothing yet? It is still starting. Run the command again in a few seconds.
-
Open the link and create your account. The password needs at least 8 characters, including a lowercase letter, an uppercase letter, a digit and a special character. You are signed in and land on Chatflows.
-
Try the demo. Chatflows shows a Try the demo card. Select Add a model key, choose OpenAI API, give it a name, paste the key, and select . The key is stored encrypted. Then select : a ready-made customer care team opens with its chat open. Select the first starter question, a complaint about a late espresso machine. The run card shows Harness Prime sending the work to the customer, operations and policy specialists, which run in parallel, and the answer gives the decision, the reply to the customer, the actions and the evidence. All the data is made up. shows each step, and the bakery quickstart on the same card.
Next: put a pipeline behind your team, give a specialist its own tables, or publish a chatflow. Docker settings, volumes and upgrades are in Docker. To change the code, use Build from source and run the dev server.
Guides
- Docker. Install and run Cuttlely in one container on SQLite.
npx cuttlely starts the same image.
- Build from source and run the dev server. Build Cuttlely yourself, run it, and change the code with live reload.
- Harnesses. Build an agent team, try it, and call it from a chatflow.
- Context and tokens. How a team keeps each prompt to the job in front of it, and where a run shows the tokens it used.
- Analyst mode. Give a specialist its own database.
- ETL. Load, embed and search your own data.
- Canvas cards. Chatflows, agentflows and Build with AI.
- Version history. Drafts, the Publish check, restore and Dev to Prod.
- Evaluations. Build a test set, score answers, and keep Publish waiting for a pass.
- Turn real answers into tests. Save one rated answer, or a window of them, as rows in a test set.
- Fail a build when answers change. Run the Publish check from a pipeline with
cuttlely check.
- Share and embed a chat. A public link or a chat on your website, served by your Cuttlely server.
Full documentation, including running from source and the API reference: docs/README.md.
Bring your existing flows
Have flows from another tool? On Chatflows, the Import menu checks an export and opens it on the right canvas, one flow at a time. You pick your credentials again. What carries over, and what is not supported yet: Bring your existing flows.
Contributing
CONTRIBUTING.md and Build from source and run the dev server. On Node 24, pnpm verify before a pull request. Security reports go to SECURITY.md. The module boundary map is in ARCHITECTURE.md.
About and credits
Cuttlely is open source under Apache 2.0. What changed in each release is in the changelog, and which versions get fixes is in Releases and support. 1.3.1 carries two security fixes for versions up to 1.3.0: GHSA-2v98-33pc-jj6f and GHSA-4p9j-8j59-gwr7. The license text is in LICENSE.md, and attribution is in NOTICE.
Cuttlely includes open-source work from Flowise, Hermes from Nous Research and React Flow. CREDITS.md lists each project with its license and link.
Contact
Questions, partnerships or press: [email protected]. Bugs and feature ideas go to issues, and vulnerabilities go through SECURITY.md.
