FluxAgent is an open-source desktop productivity application licensed under Apache-2.0, powered by the independently maintained FluxOs MIT-licensed kernel. It provides local projects, conversations, tools, approvals, browser/computer/terminal adapters, and plugins through an Electron workbench.
Use Node.js 22.13+, npm and ripgrep. Clone both repositories as siblings and check out the kernel revision declared by FluxAgent:
git clone https://github.com/StarWardAI/FluxOs.git
git clone https://github.com/StarWardAI/FluxAgent.git
cd FluxAgent
git -C ../FluxOs checkout "$(node -p 'require("./package.json").fluxOsRevision')"
npm ci
npm run dev:desktopnpm ci also installs the sibling kernel dependencies. The kernel source is maintained only in FluxOs; product packages consume declared @fluxos/* exports. Product packages use @fluxagent/*. Their private: true npm flag prevents accidental registry publication; it does not restrict the Apache-2.0 source license.
The checkout command is for a fresh sibling clone. Preserve existing working changes before changing revisions. package.json declares fluxOsRevision (the immutable CI baseline) and fluxOsVersion (the package version); they serve different purposes. Local file dependencies build the current sibling working tree, including dirty changes, so a local build is not proof of a clean pinned build. Record both repository HEADs, dirty state and source/build digests with acceptance evidence.
Local macOS signing setup requires Homebrew OpenSSL 3 (brew install openssl@3). Before packaging, run node scripts/setup-local-signing.mjs once to create a local development signing certificate. Official signed and notarized releases still require the appropriate Apple developer credentials.
npm run build:packages
npm run type-check:all
npm test
npm run test:core
npm run test:desktop
npm run test:remote
npm run verify:boundary
npm run verify:architecture
npm run verify:workspace
npm run package:dir --workspace @fluxagent/desktopDesktop uses macOS, Windows and Linux native shells. Signing/notarization requires the appropriate platform and developer credentials. Native computer control currently requires macOS permissions. CI is separated from core CI and pins a core commit; CI success does not substitute for foreground native acceptance.
Desktop supports both FluxAgent-managed models and custom API connections. In the model settings, add your own endpoint, API key and model ID, then select the connection from the composer model picker. Custom connections support OpenAI Chat Completions, OpenAI Responses and Anthropic Messages formats. Their inference requests go directly to the configured provider rather than through the FluxAgent managed-model backend. You supply your own provider access and credentials.
Official accounts (email verification, password sign-in, GitHub OAuth and device sessions) are provided by the separate, private FluxAgent Cloud service; this repository contains only the desktop client side. Desktop defaults to https://app.starwardcn.com/fluxagent-account. See product accounts for the client contract. For local development, set FLUXAGENT_ACCOUNT_URL to a loopback address serving a compatible account API before starting Desktop.
Managed models use the account service's model catalog and authentication. See managed desktop models for the two connection paths and backend contract. The current desktop welcome screen still requires an account sign-in to enter the workbench, including when using a custom API connection. This application login requirement is separate from the custom provider's authentication; FLUXAGENT_ACCOUNT_URL can point Desktop at a compatible account service.
The open-source license covers the repository's source code. Hosted services, model credits, provider credentials and platform signing credentials are not included with a source checkout. Custom model connections do not require FluxAgent-managed model access or credits; managed models require a configured account and model backend.
FluxAgent uses the current app identity, data directory, API, environment variables and media protocol. During development, schemas and local data are updated directly; old aliases, fallback readers and runtime migrations are not maintained. See current development format.
FluxAgent is licensed under Apache License 2.0. FluxOs remains independently MIT licensed. Historical MIT source retains its notice in LICENSE.legacy-MIT, and third-party components retain their own licenses and attribution notices. See NOTICE for attribution.
Bug reports and pull requests are welcome. Read Contributing before submitting changes, and use the private reporting instructions in Security for vulnerabilities.
See package architecture, repository boundary and migration record.