How Do I Start Building Workflows Locally with Hexabot?

Updated

Install the official Hexabot CLI, scaffold a project from the starter template, then run the local stack — four commands get you from nothing to a running self-hosted workspace. You need Node.js with npm available on your machine, since the CLI is distributed as an npm package. The result is a complete automation workspace where you can define workflows, connect channels, and extend the runtime with actions and tools.

Prerequisites

  • Node.js and npm installed and on your PATH (the CLI is installed globally via npm).
  • A terminal in the directory where you want the project created.
  • No cloud account is required for the local steps below — the starter template sets up a self-hostable project on your own machine.

Step-by-Step Setup

1. Install the Hexabot CLI

npm install -g @hexabot-ai/cli

This installs the hexabot command globally. Expected result: running hexabot in a terminal shows the CLI's available commands.

2. Create a project from the starter template

hexabot create my-project

Replace my-project with your preferred name. The starter template generates a complete automation workspace rather than an empty skeleton — it includes the structure for defining workflows, connecting channels, and extending the runtime with actions and tools.

3. Move into the project workspace

cd my-project

4. Run the local Hexabot stack

hexabot dev

This starts the local development stack. Expected result: the stack comes up locally and you can begin building and testing workflows against it.

What the Starter Template Gives You

The scaffolded project is the foundation for everything Hexabot does at runtime:

Capability What it means for your local build
Workflow definition Model flows visually or as portable YAML with typed contracts and schema validation
Channels Connect web, messaging, social, and custom channels
Actions and bindings Wire reusable actions, LLM calls, and external systems with defined input/output contracts
Memory, RAG, and MCP Add managed memory, retrieval-augmented context, and MCP integration points
Human review Use conditionals, loops, segmentation, inbox workflows, and live handoff
Service operations Run multilingual assistants with roles, analytics, and team control

Because flows can be expressed as YAML with typed contracts and schema validation, the project works well with version control — you can review and diff workflow changes like any other code.

Verifying It Works

After hexabot dev starts, confirm the stack is running locally before investing time in workflow design. Then build a minimal flow — for example, a chat-triggered workflow that calls a model or an API — and test it in the local environment. If the stack starts but a workflow fails, the problem is in the flow definition or a binding contract, not the installation.

Common Sticking Points

  • hexabot command not found after install: the global npm bin directory isn't on your PATH. Check your npm prefix and shell configuration.
  • Wrong directory: hexabot create must run where you want the project folder to appear; cd into the new folder before hexabot dev.
  • Port conflicts on the local stack: if another service occupies a required port, the stack may fail to start — stop the conflicting service or adjust the configuration.
  • Skipping the starter template: starting from an empty project means you lose the pre-wired structure for workflows, channels, and actions that the template provides.

When to Move Beyond Local

The local stack is for building and testing. When you're ready for production, Hexabot is designed to be self-hosted so your production data stays under your control. Pricing is tiered by operational usage — the site lists Starter, Pro, and Unlimited plans and notes that you start free and upgrade as users, workflows, and license activations become production signals. Check the pricing page for current terms before committing to a plan.