How to Set Up a New Hexabot Project: From Zero to Your First AI Automation Workspace
If you are building AI automations, customer support workflows, internal assistants, or conversational agents, you usually face the same problem very early:
You do not just need an LLM.
You need a runtime.
You need workflows. You need actions. You need memory. You need channels. You need a way to connect tools, APIs, business logic, and human intervention without letting the LLM improvise everything at runtime.
That is exactly where Hexabot comes in.
Hexabot v3 is an AI automation platform designed for developers who want to build and run agentic workflows across channels using actions, YAML workflows, memory, tools, MCP, and RAG. In this guide, we will set up a fresh Hexabot project, run it locally, understand the generated project structure, and see how to prepare it for AI-assisted development with coding agents such as Claude Code, OpenAI Codex, Cursor, or similar tools.
By the end, you will have a running Hexabot workspace ready for your first workflow automation.
What We Are Going to Build
We will create a new Hexabot project using the official CLI.
The goal is simple:
hexabot create support-automation
cd support-automation
hexabot dev
That gives us a local Hexabot development environment where we can start designing workflows, adding actions, testing automations, and eventually connecting channels, tools, and MCP servers.
For this tutorial, let’s imagine we are preparing a support automation project that can eventually:
classify incoming support requests,
extract urgency and customer information,
create tickets,
escalate high-priority cases,
and keep humans in control when needed.
But first, we need the project running.
Prerequisites
Before creating a Hexabot project, make sure you have the following installed:
node -v
Hexabot v3 requires Node.js 20.19.0 or newer.
You also need one JavaScript package manager. Hexabot works with:
npm
pnpm
yarn
bun
For local development, Docker is optional. You can start with the default local setup first, then switch to Docker when you need Docker-based services such as Postgres or other infrastructure components.
A good minimum setup is:
Node.js >= 20.19.0
npm or pnpm
Git
Docker Desktop or Docker Engine, optional
If you are using Docker on Windows, make sure Docker Desktop is configured with WSL 2 support enabled.
Step 1: Install the Hexabot CLI
The Hexabot CLI is the main entry point for creating and managing Hexabot projects.
Install it globally:
npm install -g @hexabot-ai/cli
After installation, check that the command is available:
hexabot --help
You can also use the CLI without installing it globally:
npx @hexabot-ai/cli --help
The global installation is convenient if you expect to create and manage several Hexabot projects.
Step 2: Create a New Hexabot Project
Now create a new project:
hexabot create support-automation
This command scaffolds a new Hexabot automation workspace from the official starter template.
Then enter the project folder:
cd support-automation
During project creation, the CLI will prepare the workspace, install dependencies, bootstrap environment files, and ask for initial admin credentials.
These credentials are used to access your local Hexabot admin interface, so choose something you can remember for development.
Step 3: Run Hexabot Locally
Once the project is created, start the development server:
hexabot dev
This is the simplest local development mode. It is the recommended starting point when you want to explore Hexabot without introducing Docker complexity too early.
By default, the local endpoints are:
Admin UI: http://localhost:3000
API: http://localhost:3000/api
API docs: http://localhost:3000/docs
Open the Admin UI in your browser:
http://localhost:3000
Log in using the admin credentials you created during setup.
At this point, your Hexabot project is running.
Step 4: Run Hexabot with Docker and Postgres
Local development is great for getting started, but many real-world automations eventually need Docker-based services.
For example, you may want to run Hexabot with Postgres:
hexabot dev --docker --services postgres
This tells the CLI to run the project using Docker Compose and enable the Postgres service overlay.
The CLI handles the Compose configuration for you. It can stitch together the base Docker Compose file with service-specific overlays such as Postgres, API, frontend, or other configured services.
For day-to-day development, you can start simple with:
hexabot dev
Then move to Docker when your project needs a production-like environment:
hexabot dev --docker --services postgres
Step 5: Check Your Environment
Hexabot includes a useful diagnostic command:
hexabot check
This verifies your local environment, project structure, Node.js version, environment files, and optionally Docker readiness.
If you only want to check Docker-related requirements, run:
hexabot check --docker-only
This is especially useful when onboarding a new developer, preparing a demo, or debugging an environment issue before assuming the problem is inside the application.
Step 6: Understand the Important CLI Commands
Once your project is created, these are the commands you will use most often.
Create a project
hexabot create my-project
Creates a new Hexabot project from the starter template.
You can force a package manager:
hexabot create my-project --pm npm
You can also skip dependency installation:
hexabot create my-project --no-install
Run in development mode
hexabot dev
Runs your project locally.
With Docker:
hexabot dev --docker --services postgres
Start in production mode
hexabot start
Or with Docker:
hexabot start --docker --services api,postgres --build
Manage environment files
hexabot env init
hexabot env init --docker
hexabot env list
Use these commands to initialize or inspect local and Docker environment files.
Manage Docker services
hexabot docker up
hexabot docker down
hexabot docker logs
hexabot docker ps
These commands are convenience wrappers around Docker Compose.
Run diagnostics
hexabot check
This is your first stop when something does not start correctly.
Step 7: What Makes a Hexabot Project Different?
A Hexabot project is not just another chatbot app.
The core idea is to separate workflow logic, actions, channels, memory, and integrations in a way that gives developers more control over how AI automation behaves.
Instead of asking an LLM to reason through every step every time, Hexabot lets you define deterministic business logic as actions and orchestrate those actions through workflows.
That matters because production AI automation needs more than creativity. It needs structure.
A support workflow, for example, may include:
flow:
- do: classify_issue
- conditional:
when:
- condition: "=$output.classify_issue.urgency = 'high'"
steps:
- do: escalate_to_human
else:
steps:
- do: create_ticket
- do: send_confirmation
In this kind of workflow, the LLM can help classify, summarize, or extract information, but your business rules remain explicit.
That is the difference between “the AI decided something” and “the workflow executed a controlled automation.”
Step 8: Prepare Your Project for AI Coding Agents
One of the most exciting parts of Hexabot v3 is that it can fit naturally into modern AI-assisted development workflows.
If you use tools like Claude Code, OpenAI Codex, Cursor, or similar coding agents, you can use them to help create actions, write workflows, and interact with your Hexabot project.
The recommended setup is to install the Hexabot skills:
npx skills add hexabot-ai/action-creator
npx skills add hexabot-ai/workflow-writer
These skills help your AI coding agent understand how to generate Hexabot-compatible actions and workflows.
For example, instead of asking your coding agent:
Create some code that calls HubSpot.
You can be more specific:
Use the Hexabot action creator skill to create an action called create_hubspot_lead.
The action should accept:
- email
- firstName
- lastName
- company
- message
It should call the HubSpot API and return:
- leadId
- status
Or for workflows:
Use the Hexabot workflow writer skill to create a support triage workflow.
The workflow should:
1. classify the user message,
2. detect urgency,
3. create a ticket,
4. escalate to a human if urgency is high,
5. send a confirmation message otherwise.
This gives your AI coding agent better context, better constraints, and a better chance of producing code that matches Hexabot conventions.
Step 9: Enable MCP for Deeper Agent Integration
Hexabot also includes MCP support, which allows compatible AI coding agents to interact with Hexabot through the Model Context Protocol.
In practical terms, this means an AI coding agent can inspect and manage parts of your Hexabot project through a structured interface instead of relying only on static files.
Hexabot’s MCP server can expose capabilities such as:
workflows,
workflow runs,
actions,
memory definitions,
credentials metadata,
MCP servers,
CMS content,
and RAG content.
To enable the MCP server, configure the MCP environment variables in your API environment file:
MCP_ENABLED=true
MCP_SERVER_NAME=hexabot-api
MCP_SERVER_TITLE=Hexabot API MCP Server
MCP_SERVER_VERSION=1.0.0
Then restart the API.
The local MCP endpoint is:
http://localhost:3000/api/mcp
A typical MCP client configuration looks conceptually like this:
{
"mcpServers": {
"hexabot": {
"type": "http",
"url": "http://localhost:3000/api/mcp",
"headers": {
"Authorization": "Bearer hbt_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
The bearer token should be created from your Hexabot account and used by your MCP-compatible client.
Once connected, an AI coding agent can work with Hexabot in a much more structured way. It can inspect existing workflows, validate YAML, check actions, review workflow runs, and help you iterate faster.
Step 10: Recommended Developer Workflow
A clean Hexabot development workflow looks like this:
npm install -g @hexabot-ai/cli
hexabot create support-automation
cd support-automation
hexabot check
hexabot dev
Then, when you need Docker:
hexabot dev --docker --services postgres
When you need to inspect the environment:
hexabot env list
When you want AI-assisted workflow development:
npx skills add hexabot-ai/action-creator
npx skills add hexabot-ai/workflow-writer
And when you want deeper integration with coding agents:
MCP_ENABLED=true
MCP_SERVER_NAME=hexabot-api
MCP_SERVER_TITLE=Hexabot API MCP Server
MCP_SERVER_VERSION=1.0.0
This gives you a strong foundation for building production-ready AI automation.
Common Troubleshooting Tips
The hexabot command is not found
Make sure the CLI is installed globally:
npm install -g @hexabot-ai/cli
Or use the npx version:
npx @hexabot-ai/cli --help
The project does not start
Run:
hexabot check
This will help you identify missing environment files, unsupported Node.js versions, or Docker issues.
Docker services fail to start
Check Docker status:
docker ps
Then inspect Hexabot services:
hexabot docker ps
hexabot docker logs
If needed, restart with:
hexabot docker down
hexabot dev --docker --services postgres
Environment variables are missing
Initialize local env files:
hexabot env init
For Docker:
hexabot env init --docker
Then verify:
hexabot env list
Why This Setup Matters
The best AI automation systems are not built by throwing every decision at an LLM.
They are built by combining:
predictable workflow logic,
typed actions,
business rules,
human escalation,
memory,
retrieval,
and AI reasoning where it actually adds value.
Hexabot gives developers a structured way to build exactly that.
You can start small with a local project, define your first workflow, add custom actions, connect channels, expose tools through MCP, and gradually move toward production.
The setup is simple:
npm install -g @hexabot-ai/cli
hexabot create support-automation
cd support-automation
hexabot dev
But what you get is much more than a starter app.
You get a foundation for building AI automation systems that are controlled, extensible, and ready for real business workflows.
Final Thoughts
If you are a developer, startup founder, CTO, or AI automation builder, Hexabot is worth exploring because it gives you a practical middle ground between rigid no-code automation and fully improvised agentic systems.
You keep the flexibility of AI.
You keep the control of software engineering.
And you get a framework where workflows, actions, memory, MCP, and channels are designed to work together from the beginning.
Start with a new project, run it locally, and build your first workflow.
That is where the real fun begins.
