{"id":49033405,"url":"https://github.com/cypher-asi/aura-os","last_synced_at":"2026-05-31T02:03:23.058Z","repository":{"id":344320939,"uuid":"1180401653","full_name":"cypher-asi/aura-os","owner":"cypher-asi","description":"The official OS for aura-harness, aura-swarm and aura network services. ","archived":false,"fork":false,"pushed_at":"2026-05-25T12:12:45.000Z","size":236724,"stargazers_count":4,"open_issues_count":13,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-25T12:23:05.882Z","etag":null,"topics":["aura"],"latest_commit_sha":null,"homepage":"https://aura.ai","language":"TypeScript","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/cypher-asi.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":"docs/security-audit-2026-03-29.md","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-03-13T02:16:21.000Z","updated_at":"2026-05-25T12:12:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cypher-asi/aura-os","commit_stats":null,"previous_names":["cypher-asi/aura-code","cypher-asi/aura-os"],"tags_count":179,"template":false,"template_full_name":null,"purl":"pkg:github/cypher-asi/aura-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypher-asi","download_url":"https://codeload.github.com/cypher-asi/aura-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716342,"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-05-31T02:00:06.040Z","response_time":95,"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":["aura"],"created_at":"2026-04-19T10:03:08.721Z","updated_at":"2026-05-31T02:03:23.042Z","avatar_url":"https://github.com/cypher-asi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eAURA\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eContinuous Agentic Coding\u003c/b\u003e\u003cbr\u003e\n  A local desktop app that turns requirements into structured specs and autonomously executes implementation tasks against agent workspaces.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e · \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e · \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e · \u003ca href=\"#principles\"\u003ePrinciples\u003c/a\u003e · \u003ca href=\"#specs\"\u003eSpecs\u003c/a\u003e\n\u003c/p\u003e\n\n## Overview\n\nAura is a desktop application for continuous agentic coding. It reads a project's `requirements.md`, uses AI to generate a structured implementation spec, extracts ordered tasks, and then runs an autonomous development loop that works through those tasks against the attached agent's workspace.\n\nThe core workflow follows a strict hierarchy: **Project → Spec → Task**. Agents operate within sessions, rotating context automatically when the window fills, so execution can continue indefinitely without manual intervention.\n\nPersisted browser-owned state lives client-side in IndexedDB, while the local backend keeps only lightweight JSON/runtime state needed for local execution. The backend is Rust (Axum), the interface is React + TypeScript served through a native desktop shell (tao + wry), and the LLM provider is the Claude API. Optional remote services (configured via `.env`) include **aura-network** (orgs/project sync), **aura-storage** (execution data), **billing** (credits), **aura-integrations** (secret-backed integrations), and **Orbit** (Git/repo hosting).\n\n---\n\n## Core Concepts\n\n1. **Projects:** The top-level container for metadata, planning, and execution history. Specs, tasks, and agent instances belong to a project, but the executable workspace lives on the agent instance rather than the project itself.\n\n2. **Specs:** AI-generated structured implementation plans produced from the project requirements. Each spec is a standalone markdown file, ordered from most foundational to least foundational, covering purpose, interfaces, use cases, and dependencies.\n\n3. **Tasks:** Concrete units of work extracted from specs. Each task tracks its own state through a full lifecycle: `pending` → `ready` → `in_progress` → `done` / `failed` / `blocked`. Tasks carry dependency information so the agent loop can resolve execution order automatically.\n\n4. **Agents \u0026 Sessions:** Autonomous workers that execute tasks. An agent instance picks the next available task, loads relevant spec context, performs the work against its local or remote workspace, and updates state. When the context window fills past a threshold, the agent rolls over into a new session, carrying forward only a compressed summary, and continues seamlessly.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Rust toolchain `1.94.1`\n- Node.js `25.9.0` and npm\n- Java `26` for Android validation and release lanes\n- Ruby `4.0.2` for iOS and Android release lanes\n- Xcode `26` (iOS 26 SDK) for iOS validation and release lanes — required by App Store Connect since 2026-04-28\n- Vendored [ZUI](https://github.com/cypher-asi/zui) source already included under `vendor/zui`\n\n### CI Runtime Parity\n\nGitHub Actions now uses the same explicit runtime matrix across desktop, mobile, and eval workflows:\n\n- Node.js `25.9.0` via [`.nvmrc`](.nvmrc)\n- Rust `1.94.1` via [`rust-toolchain.toml`](rust-toolchain.toml)\n- Java `26` for Android native lanes\n- Ruby `4.0.2` for mobile release lanes\n- Xcode `26` selected explicitly on the `macos-26` runner image for the iOS lanes\n\nUse the shared parity scripts from the repo root before pushing changes:\n\n```bash\nnode scripts/ci/check-runtime.mjs desktop\nnode scripts/ci/verify-desktop.mjs --smoke\nnode scripts/ci/verify-evals.mjs smoke\n```\n\nFor native mobile validation:\n\n```bash\nnode scripts/ci/check-runtime.mjs ios --native\nnode scripts/ci/check-runtime.mjs android --native\n```\n\nDesktop packaging parity also expects an `aura-harness` checkout next to this repo, or an `AURA_HARNESS_DIR` override that points to that checkout.\n\n### Environment and `.env`\n\nCopy the example env file and set at least your Claude API key:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and set:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ANTHROPIC_API_KEY` | **Yes** | Your Anthropic API key for spec generation and agent execution |\n| `BILLING_SERVER_URL` | No | Credits/billing server (default: `https://billing.zero.tech`) |\n| `AURA_NETWORK_URL` | No | aura-network backend for orgs/sync (e.g. `https://your-network-host.example.com`). Omit for local-only. |\n| `AURA_NETWORK_FEEDBACK_URL` | No | Optional Feedback-only aura-network override. Leave unset normally so Feedback shares `AURA_NETWORK_URL`; set it only when intentionally testing a different aura-network deployment for `/api/feedback/*`. |\n| `AURA_NETWORK_AUTH_TOKEN` | No | Auth token for aura-network (when using `AURA_NETWORK_URL`) |\n| `AURA_STORAGE_URL` | No | aura-storage URL for execution data (e.g. `https://your-storage-host.example.com`). Omit to disable. |\n| `ORBIT_BASE_URL` | No | URL of the **standalone Orbit service** (host and port). Aura connects to this service as a client; it does not run the Orbit API. Omit to disable Orbit features. |\n| `GITHUB_APP_*` | No | GitHub App ID, private key, and slug for repository linking |\n\nThe server reads `.env` from the current working directory when you run `aura-os-server` or `aura-os-desktop`.\n\n### Authentication\n\nAll protected API endpoints require a JWT via `Authorization: Bearer \u003ctoken\u003e` header. WebSocket connections use `?token=\u003cjwt\u003e` query parameter. The JWT is obtained from the `/api/auth/login` or `/api/auth/register` response (`access_token` field) and persisted client-side in IndexedDB with an in-memory runtime cache for active requests. The same auth flow works for both the desktop app and web deployment.\n\n### Dev vs Stable channel\n\nAURA ships in two flavors that can run side-by-side on one machine so you can use the installed stable AURA to build the next version of AURA without colliding on local files, ports, or single-instance locks.\n\n| Identifier | Stable (installed) | Dev (`cargo run`) |\n| --- | --- | --- |\n| Data dir | `%LOCALAPPDATA%\\aura` (`~/Library/Application Support/aura`, `~/.local/share/aura`) | `…\\aura-dev` |\n| User skills | `~/.aura/skills` | `~/.aura-dev/skills` |\n| Standalone server port | `3100` | `3101` |\n| Embedded desktop server port | `19847` | `19848` |\n| Harness sidecar port | `19080` | `19081` |\n| Default harness URL port | `8080` | `8081` |\n| Vite dev server port | `5173` | `5174` |\n| Window title | `AURA` | `AURA Dev` |\n| Windows single-instance mutex | `Local\\com.aura.desktop.single-instance` | `Local\\com.aura.desktop-dev.single-instance` |\n| Auto-updater | enabled | disabled |\n\nChannel selection is a build-time cargo feature on `aura-os-core`. The default is **`dev-channel`**, so plain `cargo run -p aura-os-desktop` (and `cargo run -p aura-os-server`, and the `scripts/dev/*` runners) produces a Dev binary that coexists with an installed stable AURA — different window title, different data dir, different ports, different single-instance mutex, and the in-app updater is disabled. Stable (published-installer) binaries are produced exclusively by the release pipeline, which passes `--no-default-features --features stable-channel` explicitly in `scripts/ci/verify-desktop.mjs`, `release-stable.yml`, `release-nightly.yml`, and the `before-packaging-command` for `cargo packager`. There is no runtime override — the channel is baked into the binary.\n\nRemote services (`AURA_NETWORK_URL`, `AURA_STORAGE_URL`, `BILLING_SERVER_URL`, `ORBIT_BASE_URL`, etc.) are unaffected by the channel and shared via `.env`.\n\nIf you run `npm run dev` directly (without the dev script wrapper) and want it to talk to a dev-channel `aura-os-server`, set `AURA_SERVER_PORT=3101` so the Vite proxy targets the dev backend instead of the stable one on `3100`.\n\n### Server URLs (local development)\n\n- **Backend (Axum):** `http://127.0.0.1:3100` — API at `/api`, WebSocket at `/ws` (stable; dev-channel uses `3101`)\n- **Frontend (Vite dev):** `http://localhost:5173` — proxies `/api` and `/ws` to the backend (stable; dev-channel uses `5174`)\n\n### Run backend\n\nFrom the repo root (so `.env` is found):\n\n```bash\ncargo run -p aura-os-server\n```\n\nThe Axum server listens on `http://127.0.0.1:3100`.\n\n### Run interface (dev)\n\n```bash\ncd interface\nnpm install\nnpm run dev\n```\n\nOpen `http://localhost:5173`. The Vite dev server proxies `/api` and `/ws` to `http://localhost:3100`, so the backend must be running.\n`npm install` also primes the vendored `vendor/zui` runtime dependencies, so no sibling ZUI checkout is needed.\n\n### Run desktop app (live dev)\n\nFrom the repo root:\n\n```bash\n./scripts/dev/run-desktop-dev.sh\n```\n\nOn Windows PowerShell:\n\n```powershell\n./scripts/dev/run-desktop-dev.ps1\n```\n\nThis starts Vite first, waits for `@vite/client`, then launches `aura-os-desktop` against the live frontend URL so CSS and TypeScript edits update in the native shell without rebuilding. The runner passes `--no-default-features --features dev-channel` to cargo for clarity, but plain debug runs (`cargo run -p aura-os-desktop`) also produce a Dev binary now that `dev-channel` is the default — both safely coexist with an installed stable AURA on data dir, ports, and the single-instance lock.\n\n#### Use an external harness\n\nTo run the desktop shell against a separately-running harness (for example, a sibling `aura-harness` checkout you started yourself), set `LOCAL_HARNESS_URL` to that harness URL and pass `--external-harness`:\n\n```bash\nLOCAL_HARNESS_URL=http://127.0.0.1:3404 cargo run --no-default-features --features dev-channel -p aura-os-desktop -- --external-harness\n```\n\nWith `--external-harness` the desktop binary refuses to start if `LOCAL_HARNESS_URL` is unset or `/health` is unreachable, and will not spawn the bundled local harness sidecar. The runtime config surfaces this as `AURA_DESKTOP_EXTERNAL_HARNESS=1` so the UI can reflect that the harness is externally managed.\n\nThe standard external harness runtime selects its command execution policy in code rather than through env-based command switches. Its `/health` response should report `run_command_enabled: true`, `shell_enabled: true`, and a non-empty `binary_allowlist`; if any of those are missing or disabled, restart the harness with the current autonomous-agent runtime policy before starting the dev loop.\n\n### Run mobile web\n\nFor all mobile browser testing, use the shared mobile dev runner from the repo root:\n\n```bash\n./scripts/dev/run-mobile-dev.sh\n```\n\nWhat it does:\n\n- starts `aura-os-server` on `AURA_SERVER_HOST:AURA_SERVER_PORT`\n- starts the interface on `AURA_FRONTEND_HOST:AURA_FRONTEND_PORT`\n- prints the exact URL you should open for simulator or phone testing\n- fails fast if those ports are already in use, so the printed URLs stay accurate\n\nMobile is designed as a remote-backed experience. Keep the mobile runner pointed\nat remote services rather than treating the phone as a local-workspace host.\n\nRecommended mobile setup:\n\n```bash\nAURA_NETWORK_URL=https://aura-network.onrender.com\nAURA_STORAGE_URL=https://aura-storage.onrender.com\nORBIT_BASE_URL=https://orbit-sfvu.onrender.com\n```\n\n#### Use iOS Simulator / Android Emulator\n\nUse the defaults:\n\n```bash\n./scripts/dev/run-mobile-dev.sh\n```\n\nThen open:\n\n```bash\nhttp://127.0.0.1:5173/projects\n```\n\nThis is the easiest path for simulator testing.\n\n#### Use a physical phone\n\nTo test Aura on your actual phone, your phone and computer must be on the same Wi-Fi network.\n\n1. Find your computer's LAN IP address, for example `192.168.1.42`.\n2. Start the shared mobile runner with LAN bindings and a public host:\n\n```bash\nAURA_SERVER_HOST=0.0.0.0 \\\nAURA_FRONTEND_HOST=0.0.0.0 \\\nAURA_PUBLIC_HOST=192.168.1.42 \\\n./scripts/dev/run-mobile-dev.sh\n```\n\n3. Open the printed URL on your phone:\n\n```bash\nhttp://192.168.1.42:5173/projects\n```\n\nNotes:\n\n- `AURA_SERVER_HOST=0.0.0.0` lets the local Aura host accept requests from your phone.\n- `AURA_FRONTEND_HOST=0.0.0.0` lets Vite serve the interface to your phone.\n- `AURA_PUBLIC_HOST` is only for the printed/opened URL. Set it to your machine's real LAN IP, not `0.0.0.0`.\n- If your macOS firewall prompts for access, allow incoming connections for the dev processes.\n- `127.0.0.1` only works for simulators running on the same machine. It does **not** work from a physical phone.\n\n### Install as a mobile app (PWA)\n\nIf you want the mobile experience without Safari chrome, install Aura from the browser as a home-screen app.\n\n#### iPhone / iPad (Safari)\n\n1. Open the mobile URL in Safari:\n\n```bash\nhttp://127.0.0.1:5173/projects\n```\n\nIf you are testing on a real iPhone instead of Simulator, use your LAN URL instead, for example:\n\n```bash\nhttp://192.168.1.42:5173/projects\n```\n\n2. Tap the Share button.\n3. Choose **Add to Home Screen**.\n4. Launch Aura from the new home-screen icon instead of the Safari tab.\n\nThis gives you the installed-PWA presentation, which is closer to the intended mobile shell and avoids most of the Safari URL-bar chrome.\n\n#### Android (Chrome)\n\n1. Open the same mobile URL in Chrome.\n2. Open the browser menu.\n3. Choose **Install app** or **Add to Home screen**.\n4. Launch Aura from the installed app icon.\n\nNotes:\n\n- Mobile web uses the local Aura host (`aura-os-server`) even when the underlying services are remote.\n- Some capabilities remain desktop-only by design, such as linked host folders, IDE open, and other native bridge actions.\n- Mobile project files are remote-workspace files. On mobile they are currently previewable, not editable.\n- Linked local-workspace browsing remains a desktop capability.\n- If you need different ports, set `AURA_SERVER_PORT` and/or `AURA_FRONTEND_PORT` before running the script.\n- For simulator use on the same machine, the defaults still bind to `127.0.0.1`, which is the simplest setup.\n\n### Build native mobile shells (Capacitor)\n\nAura's mobile store builds now use Capacitor on top of the existing Vite app.\n\nFrom `interface/`:\n\n```bash\nnpm install\nnpm run build:native\n```\n\nThen open the native project you want:\n\n```bash\nnpm run cap:open:ios\nnpm run cap:open:android\n```\n\nNotes:\n\n- `npm run build:native` rebuilds the web app and syncs it into the native iOS and Android shells.\n- Store-safe mobile builds currently disable in-app credit purchases. Buy or manage credits on the web app, then return to mobile.\n- If you regenerate native assets after changing the web UI, run `npm run build:native` again before archiving or uploading a store build.\n- Native shells can ship with a mobile-only default Aura API host by setting one or more Vite env vars before `npm run build`:\n  - `VITE_NATIVE_DEFAULT_HOST` for one shared native default\n  - `VITE_IOS_DEFAULT_HOST` for an iOS-specific default\n  - `VITE_ANDROID_DEFAULT_HOST` for an Android-specific default\n- Desktop and browser builds still fall back to their current origin when no host override is configured.\n- Native mobile auth is cross-origin, so the Aura API must allow credentialed CORS for native localhost origins. Add any deployed interface origins with `AURA_ALLOWED_ORIGINS`.\n\n#### Local native fastlane commands\n\nFor day-to-day native validation, use the wrapper commands from `interface/`:\n\n```bash\nnpm run mobile:android:local\nnpm run mobile:ios:local\n```\n\nOr build both in sequence:\n\n```bash\nnpm run mobile:local:all\n```\n\nWhat these commands do:\n\n- rebuild the web app\n- sync Capacitor assets into the native shell\n- build the local Android APK or iOS simulator app through `fastlane`\n- auto-detect the local gem bin, and for Android also pick up `JAVA_HOME` / `ANDROID_HOME` when available\n\nBackend env needed for a useful local mobile session:\n\n- Minimum for remote-backed projects/orgs:\n  - `AURA_NETWORK_URL`\n- Recommended full remote-backed setup:\n  - `AURA_NETWORK_URL=https://your-network-host.example.com`\n  - `AURA_STORAGE_URL=https://your-storage-host.example.com`\n  - `AURA_ROUTER_URL=https://your-router-host.example.com`\n  - `Z_BILLING_URL=https://your-billing-host.example.com`\n  - `ORBIT_BASE_URL=https://your-orbit-host.example.com`\n  - `SWARM_BASE_URL=https://your-swarm-gateway.example.com`\n\nMobile should be treated as remote-only product behavior even when you are\nrunning the local host in front of those services. Local folder attachment and\nother host-workspace actions remain desktop-only by design.\n\nNative build env used by the local wrappers:\n\n- `VITE_ANDROID_DEFAULT_HOST`\n  - default: `http://10.0.2.2:3100`\n- `VITE_IOS_DEFAULT_HOST`\n  - default: `http://127.0.0.1:3100`\n\nYou only need to override those `VITE_*` values if your backend is running on a different host or port.\n\n#### iOS TestFlight / App Store pipeline\n\nThe iOS branch now includes a `fastlane` setup under [`interface/ios`](./interface/ios) and a GitHub Actions workflow in [`.github/workflows/ios-mobile.yml`](./.github/workflows/ios-mobile.yml).\n\nLocal release commands from `interface/ios/`:\n\n```bash\nbundle install\nbundle exec fastlane ios preflight\nbundle exec fastlane ios beta\nbundle exec fastlane ios release\n```\n\nGitHub Actions release input:\n\n- Run `iOS Validation + TestFlight/App Store`\n- Pushes to `main` automatically upload the iOS beta build to TestFlight\n- Choose lane `preflight` to validate secrets/signing config, `beta` for TestFlight, or `release` for an App Store candidate\n- Set `submit_for_review=true` only when metadata, screenshots, and review notes are ready\n\nRequired iOS secrets for CI:\n\n- `IOS_APP_STORE_CONNECT_KEY_ID`\n- `IOS_APP_STORE_CONNECT_ISSUER_ID`\n- `IOS_APP_STORE_CONNECT_KEY_BASE64`\n- `IOS_DEVELOPER_TEAM_ID`\n- `IOS_MATCH_GIT_URL`\n- `IOS_MATCH_PASSWORD`\n- One match auth method:\n  - `IOS_MATCH_GIT_PRIVATE_KEY`, or\n  - `IOS_MATCH_GIT_BASIC_AUTHORIZATION`\n- Optional overrides:\n  - `IOS_BUNDLE_ID`\n  - `IOS_MATCH_GIT_BRANCH`\n  - `IOS_APP_STORE_CONNECT_TEAM_ID`\n  - `IOS_APPLE_ID`\n\nStill needed before a real App Store submission:\n\n- A live production Aura backend/API that Apple can reach during review\n- App Store Connect app record for the final bundle ID\n- Distribution signing assets in the `match` repo\n- Final app icon, screenshots, and any preview video you want to ship\n- App Privacy answers, privacy policy URL, support URL, and age rating\n- App review contact info, demo credentials, and review notes\n- Final decision on whether production builds should lock to one hosted Aura backend\n\n#### Android Play pipeline\n\nThe Android branch now includes a `fastlane` setup under [`interface/android`](./interface/android) and a GitHub Actions workflow in [`.github/workflows/android-mobile.yml`](./.github/workflows/android-mobile.yml).\n\nLocal release commands from `interface/android/`:\n\n```bash\nbundle install\nbundle exec fastlane android preflight\nbundle exec fastlane android beta\nbundle exec fastlane android release\n```\n\nGitHub Actions release input:\n\n- Run `Android Validation + Play/GitHub Release`\n- Pushes to `main` publish the signed Android APK through the separate `Mobile Nightly GitHub Release` workflow\n- Choose lane `preflight` to validate secrets/signing config, `beta` for Play Internal Testing, or `release` for a release candidate\n- Choose the Play track (`internal`, `closed`, or `production`)\n- Leave `release_status=draft` until you are ready for a real rollout\n\nRequired Android secrets for CI:\n\n- `ANDROID_PLAY_SERVICE_ACCOUNT_JSON_BASE64`\n- `ANDROID_KEYSTORE_BASE64`\n- `ANDROID_KEYSTORE_PASSWORD`\n- `ANDROID_KEY_ALIAS`\n- `ANDROID_KEY_PASSWORD`\n- Optional overrides:\n  - `ANDROID_PACKAGE_NAME`\n\nStill needed before a real Google Play submission:\n\n- A Google Play Console app record for the final package name\n- A Play service account with release permissions for that app\n- The Android upload keystore used to sign release bundles\n- Store listing copy, screenshots, and high-res app icon\n- Privacy policy URL, Data safety answers, and content rating\n- App access / review instructions if login is required\n- A live production Aura backend/API that Play reviewers can reach\n\n### Run desktop app with a built interface\n\nBuild the interface once, then run the desktop shell with the static bundle:\n\n```bash\ncd interface \u0026\u0026 npm run build \u0026\u0026 cd ..\ncargo run -p aura-os-desktop\n```\n\nRun from the repo root so `.env` is loaded. The desktop app bundles the server and interface into a single native window via WebView. In debug builds it will also try to boot a local Vite server when the repo's `interface` sources are available, while the dev scripts remain the most explicit option for pinned ports and shared dev sessions.\n\n### Release automation docs\n\nFor the current release-build plan and workflow map, see:\n\n- [Release Build Strategy](docs/release-build-strategy.md)\n- [Release Workflows](docs/release-workflows.md)\n- [Mobile Store Compliance Audit](docs/mobile-store-compliance-audit.md)\n- [ZUI Vendoring](docs/zui-vendoring.md)\n\n### Optional services\n\n- **aura-network** — When `AURA_NETWORK_URL` (and optionally `AURA_NETWORK_AUTH_TOKEN`) is set, the app can sync organizations and projects with a shared backend (e.g. `https://your-network-host.example.com`).\n- **aura-storage** — When `AURA_STORAGE_URL` is set, execution data can be stored in a remote store (e.g. `https://your-storage-host.example.com`). Omit for local-only execution.\n- **Billing** — `BILLING_SERVER_URL` defaults to `https://billing.zero.tech`; set `BILLING_INTERNAL_TOKEN` if your billing server requires it.\n- **Orbit** — Third-party standalone service for Git/repo hosting. Set `ORBIT_BASE_URL` to the Orbit service URL (e.g. `https://orbit.your-domain.com` or `http://localhost:PORT`). Aura does not run Orbit; it only connects to it as a client.\n\n---\n\n## Principles\n\n1. **Local-First:** Browser-owned state persists locally in IndexedDB, and the host backend keeps only lightweight local runtime/compatibility state. Remote services (aura-network, aura-storage, billing, aura-integrations, Orbit) are optional per feature.\n2. **Autonomous:** The dev loop runs continuously. Context rotation happens automatically when sessions fill, so the agent can work through an entire spec without manual intervention.\n3. **Transparent:** Every piece of work traces back through Task → Spec → Project. Execution logs, agent state, and session summaries are all persisted and visible in the UI.\n4. **Extensible:** A modular Rust workspace with clean domain boundaries. Each crate owns a single concern, making it straightforward to add new capabilities or swap components.\n\n---\n\n## Architecture\n\n### Apps (binaries)\n\n| Crate | Description |\n| --- | --- |\n| **aura-os-desktop** | Standalone desktop GUI (tao + wry WebView) |\n| **aura-os-server** | HTTP API server (Axum) serving the interface and API routes |\n| **aura-os-ide** | IDE helper library for opening secondary IDE windows |\n\n### Crates (libraries)\n\n| Crate | Description |\n| --- | --- |\n| **aura-os-core** | Shared entity types, IDs, enums, and settings |\n| **aura-os-store** | Lightweight local store and storage abstractions |\n| **aura-os-auth** | Authentication against external auth APIs, JWT/session types |\n| **aura-os-network** | Network client for remote org/project sync and Orbit integration |\n| **aura-os-storage** | Storage client for remote execution data (tasks, specs, sessions, logs) |\n| **aura-os-billing** | Billing client, credit tiers, and balance management |\n| **aura-os-orgs** | Organization CRUD, members, and integrations |\n| **aura-os-projects** | Project service merging network data with local compatibility state |\n| **aura-os-agents** | Agent templates, instances, and runtime management |\n| **aura-os-sessions** | Session lifecycle, context usage, and storage integration |\n| **aura-os-tasks** | Task state machine, lifecycle transitions, and locking |\n| **aura-os-harness** | Harness abstraction: WebSocket bridge, automaton client, local/swarm harness |\n| **aura-os-terminal** | PTY-based terminal for agent command execution |\n\n### Interface\n\n| Component | Description |\n| --- | --- |\n| **interface** | React 19 + TypeScript SPA (Vite), with Capacitor for native mobile shells |\n\n---\n\n## Project Structure\n\n```\naura-os/\n  Cargo.toml                  # Rust workspace root\n  apps/\n    aura-os-desktop/           # Native desktop shell (tao + wry)\n    aura-os-server/            # Axum HTTP API\n    aura-os-ide/               # IDE helper lib\n  crates/\n    aura-os-core/              # Shared types and entity IDs\n    aura-os-store/             # Local store backend\n    aura-os-auth/              # Authentication\n    aura-os-network/           # Remote network client + Orbit\n    aura-os-storage/           # Remote storage client\n    aura-os-billing/           # Credits and billing\n    aura-os-orgs/              # Organizations\n    aura-os-projects/          # Project management\n    aura-os-agents/            # Agent lifecycle\n    aura-os-sessions/          # Session and context rotation\n    aura-os-tasks/             # Task state machine\n    aura-os-harness/           # Harness / workspace bridge\n    aura-os-terminal/          # Terminal emulation\n  interface/                   # React + TypeScript SPA\n    src/\n      api/                     # API client and SSE streams\n      apps/                    # Feature modules (projects, agents, process, feed)\n      components/              # Shared UI components\n      hooks/                   # Custom hooks\n      stores/                  # Zustand stores\n      views/                   # Page-level views\n  docs/                        # Architecture, deployment, and strategy docs\n  specs/                       # Numbered implementation spec documents\n  evals/                       # Evaluation harness, promptfoo, and baselines\n  scripts/                     # Dev, release, and test automation\n  shared/                      # Cross-cutting data (tool manifests)\n  skills/                      # Bundled SKILL.md catalog by category\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypher-asi%2Faura-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypher-asi%2Faura-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypher-asi%2Faura-os/lists"}