> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interaone.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the InteraOne development stack locally and verify every application and infrastructure dependency.

This path runs infrastructure in Docker and application services through Turbo. InteraOne requires Node 20 or later, pnpm 9.15.0, Git, Docker Engine, Docker Compose, and Make.

<Note>
  The repository declares pnpm as its package manager. Do not use `npm install`; doing so creates a second lockfile and can resolve different dependency versions.
</Note>

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/InteraOne/InteraOne.git
    cd InteraOne
    ```
  </Step>

  <Step title="Check your machine">
    ```bash theme={null}
    make verify
    make check-docker
    ```

    The checks confirm Git, Node, pnpm, Docker, Compose, and the expected local ports.
  </Step>

  <Step title="Create local environment files">
    ```bash theme={null}
    make copy-env
    ```

    This copies each application's `.env.example` only when its `.env` does not already exist. Configure at least one LLM provider and one embedding provider in `apps/agent/.env`.
  </Step>

  <Step title="Start the full development environment">
    ```bash theme={null}
    make all
    ```

    The target installs dependencies, starts development infrastructure, builds and uploads the widget to MinIO, then starts the gateway, console, agent, and worker through Turbo. The launcher is deployed as an asset rather than kept in Turbo's dev process.
  </Step>

  <Step title="Verify the system">
    Open the console at [http://localhost:3000](http://localhost:3000) and call the gateway health endpoint:

    ```bash theme={null}
    curl http://localhost:3002/api/v1/health
    ```

    A healthy gateway returns `success: true`. Use `docker compose -f docker/docker-compose.dev.yml ps` to inspect infrastructure containers.
  </Step>
</Steps>

## Local service addresses

| Service       | Local address               | Purpose                             |
| ------------- | --------------------------- | ----------------------------------- |
| Console       | `http://localhost:3000`     | Operator dashboard                  |
| Gateway       | `http://localhost:3002`     | REST API and Socket.IO              |
| Agent health  | `http://localhost:4010`     | AI service health endpoint          |
| MongoDB       | `mongodb://localhost:27017` | Primary application data            |
| Redis         | `localhost:6379`            | Queues, cache, pub/sub, and streams |
| Qdrant        | `http://localhost:6333`     | Vector search                       |
| MinIO API     | `http://localhost:9001`     | Object storage and widget assets    |
| MinIO console | `http://localhost:9002`     | Object-storage administration       |
| MailHog       | `http://localhost:8025`     | Development email inbox             |
| Mongo Express | `http://localhost:8081`     | Development database browser        |
| Dozzle        | `http://localhost:8888`     | Container log viewer                |

## Useful development commands

| Command              | Effect                                                   |
| -------------------- | -------------------------------------------------------- |
| `make dev`           | Run application development processes through Turbo      |
| `make docker-start`  | Start development infrastructure only                    |
| `make docker-stop`   | Stop development infrastructure without deleting volumes |
| `make widget-deploy` | Build and upload the widget bundle to local MinIO        |
| `make build`         | Build all packages with a build task                     |
| `make lint`          | Run package lint tasks                                   |
| `make check-types`   | Run package type checks                                  |
| `make docker-logs`   | Follow development container logs                        |

<AccordionGroup>
  <Accordion title="A required port is already in use" icon="circle-alert">
    Run `make check-ports`, stop the conflicting process, and retry. Changing a port requires updating every dependent application URL, not only the container mapping.
  </Accordion>

  <Accordion title="The AI service starts but replies fail" icon="bot">
    Confirm `LLM_PROVIDER` and `EMBEDDING_PROVIDER` have matching credentials and model settings. Then check the agent log and its health endpoint on port `4010`.
  </Accordion>

  <Accordion title="The widget does not appear" icon="message-circle">
    Run `make widget-deploy`, confirm the object exists in MinIO, verify the widget public key and domain, and check `VITE_WIDGET_URL` plus the launcher's API/CDN targets.
  </Accordion>

  <Accordion title="Email does not arrive" icon="mail">
    Development defaults to MailHog. Verify the worker is running, inspect the `platform-email` queue, and open the MailHog UI on port `8025`.
  </Accordion>
</AccordionGroup>

<Warning>
  Never commit `.env` files, provider keys, JWT secrets, database credentials, or
  `AI_TOOL_SECRET`. Use different credentials in every environment and keep
  MongoDB, Redis, Qdrant, and MinIO private behind the application network.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Add knowledge" icon="database-zap" href="/knowledge-base/overview">
    Index text, documents, URLs, and FAQs for retrieval.
  </Card>

  <Card title="Install the widget" icon="code-xml" href="/channels/web-widget">
    Configure appearance, behavior, security, and the embed script.
  </Card>

  <Card title="Read the request flow" icon="workflow" href="/architecture/request-flow">
    See how messages move through Socket.IO, Redis, AI, and persistence.
  </Card>

  <Card title="Prepare production" icon="shield-check" href="/self-hosting/overview">
    Move from development defaults to a hardened deployment.
  </Card>
</CardGroup>