# ByteChef: AI agent orchestration and workflow automation in one Java platform

> ByteChef puts a drag-and-drop AI Agent component next to a general workflow engine, so tool calls, memory and guardrails live in the same canvas as your integrations. Here is how it installs, what the agent loop actually does, and where it stops fitting.

**bytechefhq/bytechef** — Open-source platform that unifies AI agent orchestration and workflow automation — autonomy and precision in one platform.

- Repository: https://github.com/bytechefhq/bytechef
- Website: https://www.bytechef.io
- Stars: 1,010 · Forks: 174
- Language: Java
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/bytechefhq-bytechef

## The gap ByteChef is aimed at: agents and integrations in one place

Most teams that put an LLM into production end up with two systems. One is an automation tool that moves data between SaaS APIs on a schedule or a webhook. The other is agent code that picks a model, decides which function to call, and loops until it has an answer. The two are wired together by hand, and the seam is where credentials, retries and audit trails get lost.

ByteChef's stated position, from the README, is that it brings both into a single platform with one orchestration layer, centralized management and enterprise-grade security. The target reader is not a solo developer writing a chatbot. It is a team that already has integration work to do and now wants an agent to sit inside that work rather than beside it. The repository topics say the same thing in shorthand: ipaas, embedded-ipaas, workflow-automation, ai-agents, mcp, self-hosted. The embedded part matters. The README describes running in regulated environments and being embedded into products that deliver AI capabilities to end users, which is a different buyer from someone who just wants a Zapier replacement.

The practical consequence is that every connector in the catalogue is also a candidate tool for the agent. That is the design bet: you do not write a separate tool layer for the agent, you reuse the integration layer you already configured. Whether that bet pays off depends on how much of your work is genuinely integration-shaped.

## How the AI Agent component actually runs

The agent is a component you drag onto the canvas, not a separate service. According to the README, it runs the full loop: model, tool selection, execution, observation, next step, with streaming and structured output. That is the ReAct-style cycle most agent frameworks implement, exposed here as a node in a workflow graph rather than as code.

The mechanism that makes tools work is annotation on component properties. The README gives the example of marking a property with fromAi("…", "STRING", { required: true }), which tells the agent that this property is a slot it can fill at runtime. Because every component is a tool under that rule, the agent's tool list is effectively the connector catalogue, and sub-workflows are tools too. That is a clean idea: composition happens through the same graph you already build.

Around the loop sit four supporting subsystems. Memory has eight backends listed, from JDBC and Redis through MongoDB, Cassandra, Cosmos DB, Neo4j, a vector-store-backed option and in-memory. Guardrails number twelve, covering PII, LLM-based PII detection, jailbreak, NSFW, topical alignment, keywords, secret keys, URLs, sanitize, custom regex, custom rules, and a violation aggregator. Knowledge bases handle ingestion and chunking against fifteen or more vector stores, with two documented RAG patterns, rag-modular and rag-questionanswer. MCP works in both directions: consume any MCP server as a tool source, or expose a workflow as an MCP tool to Claude Desktop, Cursor or Windsurf with API-key auth.

Two capabilities are marked as in development in the README: Agent Skills, described as versioned bundles of prompt, tools, memory, guardrails and knowledge bindings, and Evaluations, which lists scenarios, runs, judges (StringEquals, Regex, Contains, JsonSchema, ResponseLength, Similarity, LlmRule, ToolUsage), tool simulation and a user simulator. Treat both as roadmap, not as features you can plan a release around today.

## Installing ByteChef with Docker Compose and building a first agent

The README calls Docker Compose the fastest setup and lists Docker Desktop as the only requirement. Two commands fetch the compose file and start it. Both PostgreSQL and ByteChef containers come up automatically, and the compose file maps port 8080 for the app and 5432 for the database.

```bash
curl -O https://raw.githubusercontent.com/bytechefhq/bytechef/master/docker-compose.yml
docker compose -f docker-compose.yml up
```

When the containers are up, the README says to open http://localhost:8080/login, choose Create Account, and sign in. If the page does not load, check that the bytechef container is running rather than restarting the stack, since the app waits on PostgreSQL.

The compose file itself passes the database connection through environment variables and mounts ~/.bytechef into the container. That mount is not cosmetic. The README states that ByteChef generates the key that encrypts stored connection credentials on first start, so keeping ~/.bytechef on the host means the key survives recreating the container. Lose it and your stored credentials are unreadable.

```yaml
environment:
  - BYTECHEF_DATASOURCE_URL=jdbc:postgresql://postgres:5432/bytechef
  - BYTECHEF_DATASOURCE_USERNAME=postgres
  - BYTECHEF_DATASOURCE_PASSWORD=postgres
  - BYTECHEF_FEATURE_FLAGS
  - BYTECHEF_SECURITY_REMEMBER_ME_KEY=e48keep1this1safe3ffb2
volumes:
  - ~/.bytechef:/root/.bytechef
ports:
  - "8080:8080"
```

The README also documents a manual Docker path for environments where Compose is not available. It creates a bridge network, starts a postgres:15-alpine container on 5432, then starts the ByteChef image on the same network with the same datasource variables. Note that the manual example pins postgres:15-alpine while the compose file uses postgres:16-alpine, so the two paths are not identical.

```bash
docker network create -d bridge bytechef_network
docker run --name bytechef -it -p 8080:8080 \
    --env BYTECHEF_DATASOURCE_URL=jdbc:postgresql://postgres:5432/bytechef \
    --env BYTECHEF_DATASOURCE_USERNAME=postgres \
    --env BYTECHEF_DATASOURCE_PASSWORD=postgres \
    -v ~/.bytechef:/root/.bytechef \
    --network bytechef_network \
    docker.bytechef.io/bytechef/bytechef:latest
```

For the first real use, the README's walkthrough is eight steps: New Project then New Workflow, add a trigger, add the AI Agent component, pick a model and attach tools from the 250+ connectors plus optionally a knowledge base and guardrails, fill in credentials, configure each component's parameters in the properties panel, test, then deploy. The step people underestimate is the credentials step. The agent is only as useful as the connectors you have authenticated, and each one needs its own setup before the agent can call it.

## Where ByteChef is the wrong tool

The platform is a Java application with a PostgreSQL dependency and a canvas UI. If your problem is one LLM call behind an HTTP endpoint, that stack is overhead you will pay for on every deploy. A small service calling a provider SDK directly will be faster to build and easier to reason about.

The agent loop is also a specific shape. It is model, tool selection, execution, observation, repeat. Work that needs deterministic, auditable branching with no model in the path is better served by the plain workflow side of ByteChef, and if that is all you need, the agent component adds surface area without adding value. Conversely, if your agent needs fine-grained control over token budgets, custom sampling or a bespoke planning algorithm, you are working against a drag-and-drop abstraction rather than with it.

Two documented gaps are worth stating plainly. Agent Skills and Evaluations are both marked in development in the README, so the evaluation harness with its judges and user simulator is not something you can rely on for a release gate yet. And the licence is not a single clean identifier. The repository metadata reports NOASSERTION, the badge says Apache 2.0 plus EE, and the LICENSE file is where that split is actually defined. The README does not explain which parts fall under the enterprise edition, so anyone planning to embed ByteChef in a commercial product should read LICENSE before building on it, not after.

## How ByteChef differs from Windmill, Dapr Workflows and Conductor

The nearest comparisons people search for are Windmill, Dapr workflows and Conductor, and the difference is where the agent sits.

Windmill is a general workflow and script runner. You write scripts, typically in TypeScript or Python, and the platform handles scheduling, retries and a UI. ByteChef's equivalent layer is built from pre-made connectors and a visual editor rather than from your own scripts, which is faster when a connector exists and slower when it does not. Windmill does not present an agent as a first-class canvas node with memory, guardrails and knowledge bases attached; in ByteChef those are configured on the component itself.

Dapr workflows are a building block inside a distributed application, with the workflow engine embedded in your own services. ByteChef is the opposite arrangement: it is the application, and your integrations live inside it. If you are already running Dapr for service-to-service concerns, ByteChef becomes another system to operate rather than a library you compose with.

Conductor, from the search phrasing around AI orchestration, is a workflow engine you drive from code. ByteChef's distinguishing claim is the reverse direction: the Copilot generates workflows from a sentence, drops in configured agent steps, and explains failed runs. That is a real difference in who the tool is for. Conductor assumes you write the orchestration; ByteChef assumes someone on the team would rather describe it.

## Maintenance, releases and what the licence split means in practice

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and versioned in the 0.x range: v0.31.4 on 2026-08-13, v0.31.1 on 2026-07-14, and v0.30.0 on 2026-06-26. A minor version roughly every month is a reasonable cadence for a platform in this category, but the 0.x numbering is the honest signal. Expect breaking changes between minor versions, and pin the image tag rather than tracking latest in anything you care about. The README's own install commands use docker.bytechef.io/bytechef/bytechef:latest, which is convenient for a first look and a liability for a production deployment.

Upgrade cost is mostly the database. The compose file mounts a named volume for PostgreSQL data, so schema migrations run against persistent state on each new image. Back up that volume before pulling a new tag. The ~/.bytechef mount is the other piece of state to preserve, since it holds the credential encryption key.

On licensing, the badge describes Apache 2.0 plus EE and the repository metadata reports NOASSERTION. Those two statements are not in conflict, but they are also not a substitute for reading LICENSE. The README does not say which modules are enterprise-only, so the only way to know whether your intended use falls inside the Apache 2.0 portion is to read the file. This is a factual boundary, not legal advice: if you plan to redistribute or embed ByteChef, get the licence reviewed by someone qualified to do it.

## Conclusion

Adopt ByteChef if you want agent steps and ordinary integration workflows in one self-hosted canvas and you are willing to run PostgreSQL alongside it. Do not adopt it if you only need a single LLM call behind an API, or if a hosted SaaS is an acceptable answer. Before committing, verify the licence split between the Apache 2.0 core and the EE parts in LICENSE, and confirm that mounting ~/.bytechef is part of your container run command, because that volume holds the key for stored connection credentials.

## FAQ

### How do I install ByteChef?

The README calls Docker Compose the fastest setup and requires Docker Desktop. You download docker-compose.yml from the repository, run docker compose -f docker-compose.yml up, then open http://localhost:8080/login and create an account. A manual Docker path is also documented for environments without Compose.

### What are ByteChef AI agents and how do they work?

The AI Agent is a drag-and-drop component that runs the full loop of model, tool selection, execution, observation and next step, with streaming and structured output. Every component can act as a tool when its properties are marked with fromAi, and sub-workflows count as tools as well.

### Does ByteChef need a separate database?

Yes. Both the compose file and the manual Docker instructions start PostgreSQL alongside the ByteChef container, and the app connects through BYTECHEF_DATASOURCE_URL, BYTECHEF_DATASOURCE_USERNAME and BYTECHEF_DATASOURCE_PASSWORD.

### Which licence does ByteChef use?

The badge in the README says Apache 2.0 plus EE, while the repository metadata reports NOASSERTION. The README does not describe which parts are enterprise-only, so the LICENSE file is the place to check before embedding the platform in a product.

## Sources

- [bytechefhq/bytechef on GitHub](https://github.com/bytechefhq/bytechef)
- [Issues](https://github.com/bytechefhq/bytechef/issues)
- [Project website](https://www.bytechef.io)
- [README](https://github.com/bytechefhq/bytechef/blob/master/README.md)
- [Releases](https://github.com/bytechefhq/bytechef/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bytechefhq-bytechef