Quickstart

1. Fork & Clone

Fork the repository to your GitHub account, then clone it.

git clone https://github.com/<your-username>/InteraOne.git
cd InteraOne

2. Start InteraOne

Run:

make all

This command automatically:

Creates missing .env files from their .env.example templates
Installs all project dependencies
Pulls the required Docker images
Starts the development infrastructure
Builds the web widget
Uploads the widget to the local MinIO instance
Starts all InteraOne services

Once the setup completes, the entire InteraOne platform will be running locally.

Windows users: InteraOne currently requires WSL (Windows Subsystem for Linux). Run all setup commands from your WSL terminal rather than Command Prompt or PowerShell.

3. Configure your AI provider

Open:

apps/agent/.env

Configure at least:

LLM_PROVIDER
EMBEDDING_PROVIDER
Your provider API key(s)

InteraOne supports multiple AI providers. Without these values, the AI Agent will start but won’t be able to generate responses.

4. Verify the installation

Open the Console:

http://localhost:3000

Check the Gateway health endpoint:

curl http://localhost:3002/api/v1/health

A healthy response looks like:

{
  "success": true,
  "message": "API is healthy",
  "timestamp": "2026-07-18T05:21:32.499Z"
}

Local Development Notes

Development emails are captured by MailHog instead of being sent to real email addresses.
Whenever you make changes to the Web Widget, redeploy it locally:

make widget-deploy

Useful Commands

Command	Description
`make all`	Start the complete development environment
`make dev`	Run application services through Turbo
`make docker-start`	Start only the Docker infrastructure
`make docker-stop`	Stop Docker infrastructure
`make widget-deploy`	Rebuild and upload the widget to local MinIO
`make build`	Build every package
`make lint`	Run linting
`make check-types`	Run TypeScript checks
`make docker-logs`	View Docker container logs

Troubleshooting

A required port is already in use

Run:

make check-ports

Stop the conflicting process and try again.

The AI Agent starts but doesn't respond

Verify that your AI provider, embedding provider, and API keys are correctly configured in:

apps/agent/.env

Widget changes are not visible

Emails are not being delivered

During local development, InteraOne uses MailHog instead of sending real emails.Open the MailHog UI to inspect outgoing emails.

Next Steps

Run it locally

Start the complete development stack with pnpm, Docker, and one Make target.

Self-host in production

Deploy InteraOne to Production with a One-Click Server Setup

Understand the architecture

Follow requests across the gateway, queues, AI agent, worker, and data stores.

Explore the Agent

Understand how a single shared brain is decoupled to handle inbound and outbound communication across all channels.

Getting started

Self-hosting

Architecture

AI system

Knowledge base

Channels

Administration

Contributing

1. Fork & Clone

2. Start InteraOne

3. Configure your AI provider

4. Verify the installation

Local Development Notes

Useful Commands

Troubleshooting

Next Steps

Run it locally

Self-host in production

Understand the architecture

Explore the Agent

​1. Fork & Clone

​2. Start InteraOne

​3. Configure your AI provider

​4. Verify the installation

​Local Development Notes

​Useful Commands

​Troubleshooting

​Next Steps

Run it locally

Self-host in production

Understand the architecture

Explore the Agent

1. Fork & Clone

2. Start InteraOne

3. Configure your AI provider

4. Verify the installation

Local Development Notes

Useful Commands

Troubleshooting

Next Steps