{"id":50609744,"url":"https://github.com/mydansun/polaris-project","last_synced_at":"2026-06-06T02:30:31.484Z","repository":{"id":356618797,"uuid":"1233258577","full_name":"mydansun/polaris-project","owner":"mydansun","description":"AI full-stack app builder for end users: multiple agents turn natural-language prompts into working code, browser-verified, Git-versioned, and shipped via one-click Docker + Traefik publishes.","archived":false,"fork":false,"pushed_at":"2026-05-08T23:28:52.000Z","size":1356,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T23:30:19.938Z","etag":null,"topics":["ai-agent","code-generation","codex","coding-agent","docker-compose","fastapi","full-stack","langgraph","llm","mcp","monorepo","react","self-hosted","traefik"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mydansun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-08T19:05:52.000Z","updated_at":"2026-05-08T23:28:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mydansun/polaris-project","commit_stats":null,"previous_names":["mydansun/polaris-project"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mydansun/polaris-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mydansun%2Fpolaris-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mydansun%2Fpolaris-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mydansun%2Fpolaris-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mydansun%2Fpolaris-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mydansun","download_url":"https://codeload.github.com/mydansun/polaris-project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mydansun%2Fpolaris-project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33967639,"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-06T02:00:07.033Z","response_time":107,"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-agent","code-generation","codex","coding-agent","docker-compose","fastapi","full-stack","langgraph","llm","mcp","monorepo","react","self-hosted","traefik"],"created_at":"2026-06-06T02:30:30.331Z","updated_at":"2026-06-06T02:30:31.468Z","avatar_url":"https://github.com/mydansun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polaris\n\nPolaris turns your idea into a real, accessible full-stack application.\n\nJust describe what you want to build. Polaris writes the code, runs\nthe project, checks the result in a real browser, and publishes it as\na public website when it's ready.\n\nIt doesn't just generate code — it helps you get the application to a\nworking, usable state.\n\nPolaris 把你的想法变成一个真正能访问的全栈应用。\n\n你只需要描述想做什么,它会自动写代码、运行项目、用真实浏览器检查\n效果,并在完成后发布成一个公开网站。它不是单纯生成代码,而是帮你\n把应用做到能用。\n\n## Documentation\n\n- [README · 中文](./README.zh.md)\n- [Development](./docs/DEVELOPMENT.md) · [中文](./docs/DEVELOPMENT.zh.md)\n- [Staging](./docs/STAGING.md) · [中文](./docs/STAGING.zh.md)\n- [Architecture](./docs/ARCHITECTURE.md) · [中文](./docs/ARCHITECTURE.zh.md)\n- [API Reference](./docs/API.md) · [中文](./docs/API.zh.md)\n- [Configuration](./docs/CONFIGURATION.md) · [中文](./docs/CONFIGURATION.zh.md)\n- [Frontend](./docs/FRONTEND.md) · [中文](./docs/FRONTEND.zh.md)\n- [Roadmap](./docs/ROADMAP.md) · [中文](./docs/ROADMAP.zh.md)\n- [Testing](./docs/TESTING.md) · [中文](./docs/TESTING.zh.md)\n\n## Live demos\n\nTwo projects published from the production stack — click the\nscreenshot to open the live site, or watch the build walkthrough on\nBilibili / YouTube to see the full discovery → scaffold → publish loop.\n\n### Golf club landing page\n\n[![Golf club landing page](./docs/assets/demos/golf-club.jpg)](https://e51fff6d-9fae-423c-a6ea-1d52ceba481b.prod.polaris.surf/)\n\n[Live site](https://e51fff6d-9fae-423c-a6ea-1d52ceba481b.prod.polaris.surf/) · [Bilibili walkthrough](https://www.bilibili.com/video/BV1EsRXBEEKA/) · [YouTube walkthrough](https://youtu.be/XEX8aWYLx38)\n\n### To-Do list app\n\n[![To-Do list app](./docs/assets/demos/todo-list.jpg)](https://10011e54-a7cb-479e-a9a1-f49aa55e3a3b.prod.polaris.surf/)\n\n[Live site](https://10011e54-a7cb-479e-a9a1-f49aa55e3a3b.prod.polaris.surf/) · [Bilibili walkthrough](https://www.bilibili.com/video/BV1EsRXBEEFf/) · [YouTube walkthrough](https://youtu.be/9z6zE_Ul5ws)\n\n## Quick Start\n\n```sh\n./scripts/up.py            # prompts dev | stage, runs wizard on first run\n./scripts/up.py dev        # explicit dev (Vite HMR + uvicorn --reload)\n./scripts/up.py stage      # explicit stage (nginx-served bundle, no --reload)\n```\n\nOpen `https://${POLARIS_DOMAIN}` (default suggestion: `polaris-dev.xyz`).\nFirst-time sign-in requires an invite code (set via the wizard); on dev\nhosts you can click **Dev Login** to skip email verification.\n\n\u003e **Note on `polaris-dev.xyz`** — the authoritative DNS for this zone\n\u003e already resolves to LAN addresses on the maintainer's network, so\n\u003e developers on the same LAN can use it as-is without registering or\n\u003e configuring DNS.  Off-LAN deploys must use a domain you control on\n\u003e Cloudflare DNS (Traefik's DNS-01 ACME walks against your zone).\n\nEach mode owns its own `.env.\u003cmode\u003e` and `compose.\u003cmode\u003e.yaml` and runs\nunder its own compose project name (`polaris` vs `polaris-stage`), with\nindependent named volumes — the two stacks coexist on one host without\nclobbering each other's state.\n\n## Host Prerequisites\n\n| Tool | Purpose |\n|------|---------|\n| **Docker** (Engine or Desktop) | Everything runs in containers; `up.py` enforces this |\n| **uv** ≥ 0.11 | Resolves the inline-deps PEP 723 metadata in `scripts/*.py` |\n| **A domain on Cloudflare DNS** | TLS via ACME DNS-01; no localhost / self-signed mode.  On-LAN devs can borrow `polaris-dev.xyz` (DNS already pointing at the LAN); other deploys need a zone you own. |\n| **Codex CLI** + `codex login` | Persists Codex auth.json on host; mounted into workspaces |\n\nNo system Python venv. No system pnpm. No system Make. Editing api /\nworker / web source happens through the bind-mount; `--reload` /\nVite HMR pick changes up live without rebuilding images.\n\n## Daily Commands\n\nAll commands take an optional `dev | stage` positional; if omitted, the\nscript prompts (or defaults to `dev` under `--non-interactive`).\n\n| Command | What it does |\n|---------|--------------|\n| `./scripts/up.py [dev\\|stage]` | Configure (if needed) + start the stack.  Re-run after editing `.env.\u003cmode\u003e`. |\n| `./scripts/up.py \u003cmode\u003e --reconfigure` | Re-run the wizard even if `.env.\u003cmode\u003e` is complete. |\n| `./scripts/up.py \u003cmode\u003e --non-interactive` | CI mode — fail fast on any missing required env. |\n| `./scripts/down.py [dev\\|stage]` | Stop the stack + sweep dynamic workspace containers (preserves data). |\n| `./scripts/down.py \u003cmode\u003e --clear` | Drop platform volumes + wipe `.data/{workspaces,workspace-meta,projects}`. |\n| `./scripts/down.py \u003cmode\u003e --nuclear` | `--clear` + remove built images (api/worker/web for that mode + workspace/ide/chromium-vnc). |\n| `./scripts/build.py` | Build the workspace runtime images (idempotent — only rebuilds if Dockerfile changed).  Shared between dev and stage. |\n| `./scripts/build.py --force` | Rebuild every image regardless of mtime. |\n| `./scripts/build.py --push REGISTRY` | Tag + push to a remote registry after build. |\n\nFor ad-hoc compose ops (`logs`, `exec`, `ps`):\n\n```sh\ndocker compose -f compose.dev.yaml logs api -f\ndocker compose -f compose.dev.yaml exec api alembic upgrade head\n\n# stage variant — same shape, just swap the file:\ndocker compose -f compose.stage.yaml logs api -f\n```\n\nTip: `export COMPOSE_FILE=compose.dev.yaml` (or `compose.stage.yaml`) in\nyour shell rc to drop the `-f`.\n\n### Headless server? Use the dev VNC\n\n`compose.dev.yaml` includes a `dev-vnc` chromium container so you can\nview the running frontend from your laptop while developing on a\nremote box.  The container starts with chromium pre-pointed at\n`https://${POLARIS_DOMAIN}/`, so HMR / live-reload of `apps/web` is\nvisible immediately.\n\n```sh\n# from your laptop:\nopen https://vnc.${POLARIS_DOMAIN}/      # e.g. https://vnc.polaris-dev.xyz/\n```\n\nThe Selkies WebRTC UI loads in the laptop browser; click anywhere in\nthe chromium frame to grab control.  Routed through traefik on the\nwildcard cert — clipboard / gamepad / camera APIs work because it's a\nreal HTTPS secure context.  No auth on the route itself; **trusted\nnetwork only**.  For wider exposure set `SELKIES_PASSWORD` on the\nservice.\n\n## Running tests\n\nA single root-level uv workspace ties all the Python packages together — no\nper-package `.venv` directories any more.  First run materialises a shared\n`.venv/` at the repo root (gitignored).\n\n```sh\nuv sync --all-packages --all-extras       # one-time / after pyproject edits\n\nuv run --package polaris-api pytest apps/api/tests\nuv run --package polaris-worker pytest apps/worker/tests\nuv run --package polaris-design-intent pytest packages/design-intent/tests\n\n# scripts/ has its own self-contained env (PEP 723 inline deps + uv).\ncd scripts \u0026\u0026 uv run --group dev pytest\n```\n\nFrontend type-check + production build run inside the web container:\n\n```sh\ndocker compose -f compose.dev.yaml run --rm web pnpm typecheck\ndocker compose -f compose.dev.yaml run --rm web pnpm --filter @polaris/web build\n```\n\nRunning pnpm directly on the host (e.g. `pnpm add foo` to add a dep) still\nworks as long as you have pnpm installed; the host `node_modules/` is kept\nspecifically so VSCode / Cursor TypeScript IntelliSense remains useful.\n\n## Configuration\n\nSettings live in `.env.dev` and `.env.stage` at the repo root, one per\nmode.  The first `./scripts/up.py \u003cmode\u003e` run launches a wizard that\nwalks you through every required field with live token validation.\nRe-run with `--reconfigure` to change the domain, swap TLS modes,\nrotate keys, etc — all without touching code.\n\nField metadata (defaults / required / secret / validators) lives in\n`scripts/lib/spec.py` — a single source of truth for the wizard, the\nREADME, and CI's non-interactive checks.\n\nBoth `.env.\u003cmode\u003e` files are gitignored.  Moving the repo elsewhere on\nthe same host:\n\n```sh\n./scripts/down.py dev\nmv polaris-project ~/work/polaris\ncd ~/work/polaris\n./scripts/up.py dev    # works — every host bind-mount is `./` relative\n```\n\n## Repository Shape\n\n```\napps/\n  web/           React workbench (chat + Theia IDE / Chromium VNC)\n  api/           FastAPI control plane (auth, projects, sessions, MCP, publish)\n  worker/        Background session runner (Redis consumer, discovery + Codex)\npackages/\n  ide/            Custom Theia IDE base\n  agent-core/     PolarisCodexSession\n  design-intent/  LangGraph discovery agent\n  ui/             Shared React primitives\n  shared-types/   Shared TS API / SSE contracts\n  welcome-page/   Static welcome page for chromium-vnc\ninfra/\n  workspace/     polaris/workspace Dockerfile + workspace-side polaris CLI\n  chromium/      polaris/chromium-vnc Dockerfile + nginx CDP proxy\n  traefik/       Static + dynamic config (CF DNS-01 ACME, no host certs)\n  minio/         (compose service in compose.dev.yaml; data lives here)\n  publish-templates/  Per-stack Dockerfile + compose + polaris.yaml scaffolds\nscripts/\n  build.py / up.py / down.py    The three CLIs above\n  lib/                          Validators, env io, wizard, paths, docker_ops\n  tests/                        pytest suite (uv run --group dev pytest)\ncompose.dev.yaml   Dev stack (Vite HMR + uvicorn --reload + bind-mounted source)\ncompose.stage.yaml Stage stack (nginx-served bundle, no --reload, project name polaris-stage)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmydansun%2Fpolaris-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmydansun%2Fpolaris-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmydansun%2Fpolaris-project/lists"}