{"id":50746341,"url":"https://github.com/snowztech/helia","last_synced_at":"2026-06-10T21:30:35.515Z","repository":{"id":359249328,"uuid":"1245191389","full_name":"snowztech/helia","owner":"snowztech","description":"Open-source AI assistant for small businesses. Upload your docs, plug in your APIs, drop one script tag.","archived":false,"fork":false,"pushed_at":"2026-06-02T22:41:05.000Z","size":1229,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T00:21:02.171Z","etag":null,"topics":["ai","ai-agents","assistant","chatbot","harness","llm","nextjs","open-source","openai","rag","rag-chatbot","typescript"],"latest_commit_sha":null,"homepage":"https://gethelia.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snowztech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T02:05:35.000Z","updated_at":"2026-06-02T22:41:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/snowztech/helia","commit_stats":null,"previous_names":["snowztech/helia"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/snowztech/helia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowztech%2Fhelia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowztech%2Fhelia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowztech%2Fhelia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowztech%2Fhelia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snowztech","download_url":"https://codeload.github.com/snowztech/helia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snowztech%2Fhelia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","assistant","chatbot","harness","llm","nextjs","open-source","openai","rag","rag-chatbot","typescript"],"created_at":"2026-06-10T21:30:29.739Z","updated_at":"2026-06-10T21:30:33.544Z","avatar_url":"https://github.com/snowztech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helia\n\n\u003e Open-source AI assistant for small businesses. Upload your docs, plug in\n\u003e your APIs, drop one script tag.\n\n## Quick start\n\nThe same three commands work on your laptop or on any Linux server with\nDocker installed. No Node or pnpm needed on the host.\n\n```bash\ngit clone https://github.com/snowztech/helia\ncd helia\ncp .env.example .env\n```\n\nOpen `.env` and fill the two required values:\n\n```bash\nOPENAI_API_KEY=sk-...\nMASTER_KEY=$(openssl rand -hex 32)\n```\n\nThen bring up the stack:\n\n```bash\ndocker compose up -d\n```\n\nFirst boot takes ~30 seconds. When the api logs say `helia-api listening`,\nopen **http://localhost:3000** in your browser.\n\n```bash\ndocker compose logs -f api    # watch boot\ndocker compose down           # stop, keep data\ndocker compose down -v        # stop and wipe the database\n```\n\n## What you can do\n\nThe admin has five pages:\n\n| Page        | What it does                                                                                      |\n| ----------- | ------------------------------------------------------------------------------------------------- |\n| `/`         | Dashboard: messages this week, today, avg response, recent activity, getting-started checklist    |\n| `/sources`  | Add knowledge: PDFs, plain text, or crawl a URL                                                   |\n| `/tools`    | Register HTTP endpoints the agent can call mid-conversation                                       |\n| `/widget`   | Brand the widget, see it live, copy the install snippet                                           |\n| `/settings` | Workspace name, locale, model, API key status, allowed origins, user identity for logged-in users |\n\nGear icon (top right) → `/settings`. Theme toggle (top right) → dark/light.\n\n## Embed the widget on your site\n\nOnce you've configured the bot, `/widget` shows your install snippet:\n\n```html\n\u003cscript\n  src=\"https://your-helia-host/w.js\"\n  data-workspace=\"\u003cuuid\u003e\"\n  async\n\u003e\u003c/script\u003e\n```\n\nPaste it before `\u003c/body\u003e` on any page of your site. The widget reads\nbrand + persona from `/v1/widget/config` on mount, streams chat from\n`/v1/chat`, and renders inside a shadow DOM so host page styles cannot\nleak in or out.\n\nShowing the widget to logged-in users? Open `/settings` → User identity\nto set up a signing secret, add a backend route, and scope tool calls\nto the verified user.\n\nFor embedding while developing Helia itself (port 5173 widget dev\nserver), see [Develop](#develop).\n\n## Deploy on a server\n\nThe `docker compose up -d` above works the same on a VPS. For a real\nproduction deploy with a domain and TLS, you typically add a reverse\nproxy (Caddy / nginx / Traefik). Set the public URL in `.env`:\n\n```bash\nHELIA_WEB_URL=https://helia.yourdomain.com\nHELIA_API_URL=https://helia.yourdomain.com\nHELIA_CORS_ORIGIN=https://helia.yourdomain.com,https://app.yourdomain.com\n```\n\nStep-by-step deploy + reverse proxy + backups: [`docs/deploy.md`](./docs/deploy.md).\n\n## API\n\n| Method   | Path                     | Purpose                                            |\n| -------- | ------------------------ | -------------------------------------------------- |\n| `GET`    | `/v1/health`             | Liveness + DB check                                |\n| `GET`    | `/v1/system`             | Read-only system info (model, key status, version) |\n| `GET`    | `/v1/workspace`          | Current workspace                                  |\n| `PATCH`  | `/v1/workspace`          | Update name, locale, model, brand, layout          |\n| `GET`    | `/v1/widget/config?ws=…` | Public widget config                               |\n| `POST`   | `/v1/chat`               | AI SDK data stream (text + tool calls)             |\n| `GET`    | `/v1/metrics`            | Counts (today, week, total) + avg latency + tokens |\n| `GET`    | `/v1/conversations`      | Recent chat traces                                 |\n| `GET`    | `/v1/sources`            | List all sources                                   |\n| `GET`    | `/v1/sources/:id`        | Source detail                                      |\n| `GET`    | `/v1/sources/:id/events` | Ingest timeline                                    |\n| `POST`   | `/v1/sources/pdf`        | Multipart upload, sync ingest                      |\n| `POST`   | `/v1/sources/text`       | `{ name, text }`, sync ingest                      |\n| `POST`   | `/v1/sources/url`        | `{ url, maxPages? }`, background crawl             |\n| `DELETE` | `/v1/sources/:id`        | Cascade delete chunks + events                     |\n| `GET`    | `/v1/tools`              | List workspace HTTP tools                          |\n| `POST`   | `/v1/tools`              | Create an HTTP tool                                |\n| `PATCH`  | `/v1/tools/:id`          | Update an HTTP tool                                |\n| `DELETE` | `/v1/tools/:id`          | Delete an HTTP tool                                |\n\n## Architecture\n\n```\napps/\n├── api/      # Hono REST + SSE chat (port 4000)\n└── web/      # Next.js admin UI (port 3000)\npackages/\n├── agent/    # generic agent loop (persona + tools + maxSteps), AI SDK based\n├── db/       # Drizzle schema + Postgres client\n├── rag/      # extract / chunk / embed / retrieve / prompt / crawl / ingest\n├── react/    # React wrapper around the vanilla widget\n├── server/   # identity-signing helpers for customer backends\n└── widget/   # vanilla TS embed bundle (~20 KB minified)\n```\n\n`apps/api` plugs the agent in `src/agent/tools.ts`. The built-in\n`search_knowledge` tool binds `@helia/rag` retrieval to the workspace. On\ntop of that, any HTTP tools the workspace owner registered (via the\n`/tools` admin page) are loaded at chat time. The generic loop in\n`@helia/agent` stays app-agnostic.\n\nFull design in [`docs/architecture.md`](./docs/architecture.md). Long-arc\ndirection in [`docs/roadmap.md`](./docs/roadmap.md).\nSDK install notes live in [`docs/sdk.md`](./docs/sdk.md).\n\n**Stack** — Next.js 15 · TypeScript · pnpm workspaces · Hono · Postgres +\npgvector · Drizzle · Vercel AI SDK · OpenAI · shadcn/ui · hugeicons.\n\n## Develop\n\nHacking on the Helia codebase needs **Node 22+** and **pnpm 9+**. The\ndatabase still runs in Docker.\n\n```bash\ncp .env.example .env       # if not done yet\nmake setup                 # postgres + install + schema + bootstrap\nmake dev                   # api (4000) + admin (3000) + widget (5173) in parallel\n```\n\nUseful targets — full list with `make help`:\n\n```\nmake dev          api + web + widget in parallel\nmake dev-api      API only\nmake dev-web      admin only\nmake dev-widget   widget bundle dev server only\nmake schema       apply Drizzle migrations\nmake typecheck    strict TS across the workspace\nmake docker-up    build + start the full Docker stack (same as Quick start above)\nmake docker-logs  tail logs from all containers\n```\n\nWidget snippet pointing at the local dev bundle + API:\n\n```html\n\u003cscript\n  src=\"http://localhost:5173/dist/w.js\"\n  data-workspace=\"\u003cyour-workspace-uuid\u003e\"\n  data-api-url=\"http://localhost:4000\"\n  async\n\u003e\u003c/script\u003e\n```\n\n## Contributing\n\nFork, branch off `main`, `make setup` + `make dev`, open a PR.\n`make typecheck` must pass. See [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n\n## License\n\nAGPL-3.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowztech%2Fhelia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnowztech%2Fhelia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnowztech%2Fhelia/lists"}