Skip to content

quickstart.mdx

Latest commit

 

History

History
173 lines (122 loc) · 3.95 KB

quickstart.mdx

File metadata and controls

173 lines (122 loc) · 3.95 KB
Raw
title Quickstart
description Run the InteraOne development stack locally and verify every application and infrastructure dependency.
icon rocket

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

Run: 
```bash
make check-ports
```

Stop the conflicting process and try again.
Verify that your AI provider, embedding provider, and API keys are correctly configured in: 
```text
apps/agent/.env
```
After modifying the widget source, rebuild and upload it: 
```bash
make widget-deploy
```

Then refresh your browser.
During local development, InteraOne uses **MailHog** instead of sending real emails. 
Open the MailHog UI to inspect outgoing emails.

Next Steps

Start the complete development stack with pnpm, Docker, and one Make target. Deploy InteraOne to Production with a One-Click Server Setup Follow requests across the gateway, queues, AI agent, worker, and data stores. Understand how a single shared brain is decoupled to handle inbound and outbound communication across all channels.