main-3 is a fresh thread-based architecture, replacing Bees Desktop. The desktop app and hosted browser use the same thread screen: threads on the left, discussion and AI work in the middle, results/files on the right. On narrow screens files open in a drawer.
Install/open the desktop Client, connect an AI in Settings, and start a thread. A Default team is created automatically; its heading is hidden until there is more than one team. Use the Bees logo menu to switch organizations, create an organization, or create a team. The navigation rail shows the selected team, offers New Goal and New Chat, and opens team settings with the gear below Chat. Team menus offer creation actions, Processes, and Settings. Global, organization, and team settings open in the main right panel. No account, organization, workspace, root folder, or Drive provider is required for local work. The desktop app defaults to local execution. Accounts are needed only to share work or connect machines.
Chat alternates between your message and an AI reply, retaining conversation history for each turn. Its single Chat stage returns to Your turn after replying and resumes on your next message. Goals use Work and Review stages. Both processes inherit team instructions, memory, files, and local integrations.
Agents can present review screens with forms, editable tables, split panes, tabs, comparisons and source references for data from any workflow. Correct related fields together, save a draft, request changes or approve once. Saved reviews survive restart; interrupted work requires an explicit continuation.
Creating an organization also creates its Default team. Desktop keeps a built-in Local Org and lets you create more local organizations from Settings → Organizations. Local organizations need no account, have their own teams and work folders, and cannot be shared. They remain available beside signed-in organizations. The client repairs older empty organizations owned by the signed-in user once, without duplicating existing teams. Team owners can create, edit, and delete named processes under Team settings → Processes; editors can start threads from them. Existing threads retain their saved stages when a process is edited or deleted.
Desktop team and thread Files screens include Shared folder locations for input and output folders. Bees creates separate .bees-shared.json identity markers for owned teams and threads under their work root on initial setup. Each input or output folder has one Select folder button. Bees recognizes an existing identity marker, or creates one automatically for an unmarked folder on the owning Client; teammates select their own local path to the same externally synchronized folder. Folders belonging to another team, thread, or purpose are rejected without changing the mapping or marker. Shared documents contain folder identities, never machine paths. Changing a mapping keeps prior folders and markers; startup reports missing folders or markers rather than recreating them. Check synchronization, available in a collapsed section, uses temporary challenge and acknowledgment files to verify that an external service recently synchronized in both directions with the selected authorized Client. A copied marker alone does not confirm synchronization. New control files are excluded from attachments and generated results. This feature recognizes and checks folder mappings; it does not import folder contents or change file delivery routes. Both Clients need this feature for a synchronization check; an unreachable peer may retain temporary probes until external deletion synchronization catches up.
Each thread has exactly one owning Client. Its SQLite document and content-addressed files live in that Client's managed private storage. Run workspaces live under ~/Bees, created on first launch. Global settings → Root folder changes this location; organization administrators can set a local override under Org settings. Changing folders copies existing run files and keeps the originals; account databases and credentials stay in private application storage. Hosted Clients manage their folders automatically. Signed-in clients discover thread IDs, titles, team names, owners and status through the directory. Opening a remote thread fetches only read-only conversation text over the peer connection; it does not download files, run state or MCP settings. There is no background replication of thread contents. Select Transfer here to move the full thread and execution ownership. Viewers cannot request ownership; editors need the current owner’s approval. Thread owners control access and approvals.
Workflows have Work, Independent review, and Your approval stages. Team settings hold instructions, shared memory, workflow stages, files, timezone-aware schedules, MCP integrations, and browser access. Instructions and memory apply to all threads; a team workflow remains the default for threads without an explicitly selected process. New Goal and New Chat retain their selected process. Team schedules start a new thread per occurrence while the owning Client is running; missed occurrences coalesce into one catch-up. Existing thread settings are preserved and editable under Team settings → Existing thread settings. Integration credentials remain in private Client storage and travel only with an explicit transfer between the same user’s clients. Personal browser sessions remain local. Interrupted execution is marked uncertain and requires explicit review/retry, because an external action might already have occurred.
Team settings → Agents creates named agents with instructions, a preset, model, reasoning effort, and add-on access. Assign agents to process or workflow stages. Each run saves the chosen agent's configuration; later edits leave execution history intact. Use your own browser is on by default on supported desktop browsers, with explicit opt-outs retained.
In Add-ons → Apps, open Manage accounts, name a connection, and choose Add another account to authorize another identity for the same app. Select the accounts this team or thread may use; changes apply to its next run. Threads inherit team choices until you change their own app settings. Selecting several accounts lets one process act through each connection and report results separately, including more than ten accounts for one app. Each selected connection has its own pinned session; deselecting every account disables that app here. Connections and provider tokens remain in Composio, while local settings store only connection IDs and labels. Update Bees Server before using account selections. Facebook's Composio integration supports Pages, not personal-profile posting.
Team settings → Memory includes automatic Hindsight memory and manual shared notes. Automatic memory remembers completed goals and recalls team outcomes for new work. Desktop installers download LibreOffice, Sherpa/ONNX voice libraries, and the uv installer in the background after first launch, then install managed Python and Hindsight. Chat is available while setup runs; Office conversion, local voice, and local memory require internet for their initial setup. Voice models download separately when local voice is enabled. Downloads are verified against the manifest bundled with the app and cached in private Client storage. Automatic memory requires a running local OpenAI-compatible model; installing its dependencies does not. Outcomes queue durably while memory is unavailable. The settings let users select a local model, disable memory, correct or forget outcomes, and optionally connect their own Hindsight endpoint. Banks and credentials are isolated by Client and team; automatic memories are not synchronized to other Clients.
Share creates an email-addressed team invitation, including for vendors outside your organization. Team membership grants access to existing and future threads in the team. Existing individual thread invitations remain valid. Send the generated link to the person invited. The invited account must verify its email. The link alone does not grant access. Everyone on a shared thread uses the same configured Bees Server; private-server guests need an account and network access there. Organizations provide a colleague/client directory and SSO administration; membership never shares a thread automatically.
Transfer here requests a stopped thread from its current Client. A request from the same account needs no additional approval; a request from another team editor waits for the current owner to approve or decline it. The source waits for active work to finish, freezes the checkpoint, and delivers it over the existing encrypted peer channel. The requesting client verifies the checkpoint and file hashes and accepts ownership automatically. The source’s Offer transfer flow remains available and requires recipient acceptance. Keep the source online until acceptance; failed delivery can be retried or cancelled. Active OS/model processes are not migrated.
Transfers between the same user’s clients include cloud app selections and effective team/thread MCP definitions and credentials. They become a snapshot for the transferred thread, leaving other destination threads untouched. Remote MCP connections can run immediately if reachable; local commands and loopback connections require setup and explicit enabling on the destination. Credentials are staged in private credential storage, never in conversation documents, ordinary snapshots, or the Server database. Transfers to another user do not carry the source user’s MCP credentials or app authorizations.
| Setup | Supported behavior |
|---|---|
| One local user, no Server | Private threads, files, AI work and local schedules |
| Same account on several machines | Discover thread labels, view conversation text, and select Transfer here when needed |
| Many accounts/organizations in SaaS | One persistent isolated hosted Client per account; shared directory/relay API |
| Enterprise on a disconnected network | Desktop Clients plus a reachable private Bees Server |
| Free offline organization without a Server | Not supported; no LAN discovery or pairing |
| Vendor/external guest | Verified email invitation to an individual thread, without org membership |
Clients obtain peer addresses and per-thread grants from Bees Server. Direct HTTPS with TLS certificate trust is attempted first, followed by a direct WebRTC data channel using werift, then the encrypted live relay. WebRTC setup descriptions travel through the existing authenticated TLS relay; file traffic uses the direct channel once established. The same certificate-pinned TLS exchange and per-request authorization run on every path. WebRTC setup has a 15-second deadline; unsupported Clients or failed connections fall back to a fresh relay grant. Desktop and hosted Clients use the same transport. BEES_WEBRTC_STUN_URLS is a comma-separated list of STUN URLs (default stun:stun.l.google.com:19302); an empty value limits discovery to local addresses. STUN services learn network addresses, not file contents. No TURN service is required because the existing relay supplies fallback. No server-side work sync database or offline store exists. Fresh content and accepted changes need a reachable owner and Server. Existing local copies remain readable offline. Logging into a different Client does not transfer work automatically.
Node 24.7 and the native platform build prerequisites are required.
npm ci
npm run tauri:dev
npm run check
cargo check --manifest-path src-tauri/Cargo.toml
npm run check:headlessnpm run check covers account isolation, storage/transfer validation, tool path fences, schedules, hosted routing, OpenAI-compatible connections, subscription adapters, file locking, page fetching, and both UI builds. check:headless boots the actual Client, runs an actual agent loop against a synthetic local model, verifies independent work/review, execution deduplication, shutdown, and restart persistence. Peer transport tests live in the sibling bees-server repository and use these Client modules directly.
npm run check:web runs the full shared suite, then the same agent proof through the hosted gateway with cookie authentication and a hosted worker. It also checks rejected sessions, cross-origin requests, desktop-only onboarding, and managed web folders. The directory and model are local fixtures; it does not charge customers or modify production accounts.
Account profiles separate threads, certificates and device credentials. First startup offers a Bees organization with purchased AI credits, or a local organization using your own AI. Local mode needs no account. Organization balances stay separate from personal balances. Credits are a USD balance, with a $1 minimum purchase. Models are charged at actual OpenRouter cost plus 30%. AI Models shows the pinned platform default first, then recommended models, then Other models, with input/output prices and selected-model cache and context-tier rates. Platform admins configure the default model and effort on the Server; explicit user choices are preserved. Provider credentials never reach a Client. Hosted users get separate containers and persistent volumes.
With Tailscale running and MagicDNS plus HTTPS turned on for your tailnet, run:
npm run start:phoneIt starts headless Bees on 127.0.0.1:8090 with its state in ~/.bees-headless, serves it to your tailnet on port 8443 with tailscale serve, and prints a sign-in link. Open that link once on each device. The link gives the whole agent, shell included, so keep it private and limit the port to your own devices in your tailnet access rules. It refuses to start if port 8443 is public through tailscale funnel, already serves something else, or if port 8090 is busy. Stopping it with Ctrl+C also stops serving 8443. If your tailscaled uses its own socket, set TAILSCALE_SOCKET to that path. Delete ~/.bees-headless/phone-token to sign every device out.
Build the Client image with docker build -f deploy/headless/Dockerfile -t bees-client:main-3 .. Run npm run build:hosted for browser assets. On a dedicated Docker host, run node dsh-runtime/hosted-clients.mjs behind HTTPS using the environment template and service in deploy/hosted.
The gateway binds loopback behind your HTTPS reverse proxy. It verifies the account session on every request and proxies only the thread and file APIs. It starts one container and named durable volume per (Server origin, account ID). Containers have read-only roots, private loopback HTTP ports, bounded CPU/memory/processes, no extra capabilities and no Docker socket. Only the trusted gateway can control Docker. Set BEES_CLIENT_IMAGE to a reviewed registry digest (or immutable local sha256: image ID).
Hosted Clients use the same Bees Credits connection as desktop. Global settings → Credits shows the available balance and server address; purchases and auto-renew are managed on the Server. Refills occur at 100,000 credits remaining. Purchased organization balances are shared across active members; personal balances stay separate. Stripe Checkout collects card details and explicit recharge consent. Administrators manage refill settings on the Server. Starter requests use a server-held per-user OpenRouter key for the lifetime 50k-credit grant and do not deduct purchased credits. Purchased balances take precedence. Paid requests settle at actual OpenRouter cost plus 30%; model rejection returns credit reservations, while unconfirmed costs retain a hold for provider reconciliation. BEES_HOSTED_RUNS_PER_DAY=0 disables the separate daily run cap by default, so purchased credits are not limited to one run a day; operators can set an explicit cap. An optional private hosted provider profile remains separate from credit-backed AI. Web keeps every added account signed in and shows their organizations together in the sidebar, with emails distinguishing accounts. Switching organizations changes the current view while the other hosted Clients keep running. Browser sign-out removes only the current account from that browser. Accounts without purchased or reserved credits, auto-renew, or a pending payment stop their hosted Client on sign-out; signing back in restarts it with the same saved data. Paid Clients keep running. Stopping a free Client interrupts its active work, including work viewed in another browser. The gateway also checks existing Clients every minute and stops free Clients after five minutes without browser contact once active work finishes. Closing all tabs and expired sessions therefore release compute; the next browser request restarts the Client. Gateway restarts allow a fresh five-minute grace period. Paid or unknown credit status never triggers idle shutdown. Persistent volumes need independent backups.
For the production GKE cluster, deploy/hosted/kubernetes.yaml runs the same gateway with the Kubernetes backend. Build for linux/amd64, push the tested image, replace both __CLIENT_IMAGE__ placeholders with its full registry @sha256: digest, and apply the manifest. The existing app.bees.bot API ingress owns TLS; the new ingress routes /app, /bees-api, and /bees-auth to the Client gateway. Keep the API at one replica with Recreate while its relay registry is in memory.
Before deploying an image, run its actual Linux proof (the native-addon loader needs an executable temporary directory):
docker run --rm --platform linux/amd64 --read-only --cap-drop ALL \
--security-opt no-new-privileges --pids-limit 256 --memory 2g --cpus 2 \
--tmpfs /tmp:rw,exec,nosuid,size=512m -e BEES_PROOF_HOST=0.0.0.0 --entrypoint node \
"$BEES_CLIENT_IMAGE" scripts/check-headless.mjsKubernetes accounts receive separate non-root workers, private Services, credentials and 10 GiB retained volumes. Workers have no Kubernetes credentials. NetworkPolicy blocks other accounts, private network addresses and cloud metadata; its service CIDR exclusion and DNS service IP must match the target cluster. This manifest requires a NetworkPolicy-capable cluster and the gcp-balanced-retain storage class. The gateway defaults to ten accounts; size capacity before raising that limit. Idle Clients update on their next request; active work delays the image change. Rollback uses the previous gateway image and BEES_CLIENT_IMAGE digest and leaves account volumes intact.
For Bees Credits, apply Server migration 009_user_credits.sql and configure LLM_MODEL, LLM_BASE_URL, LLM_REASONING_EFFORT, and LLM_API_KEY on the API Server. Configure STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET there for purchases and opt-in automatic refills; see the Server README for webhook events and test-mode validation. No credit model or shared provider key belongs in a desktop bundle or hosted Client image. The desktop .env does not configure the deployed Server. Private operators can still supply an independent BEES_HOSTED_MODEL / BEES_MODEL_PROFILE through the optional bees-hosted-model Secret. Configure SMTP or Cloudflare on the API for account mail. Automatic memory needs its own local model or Hindsight service; manual team notes work independently.
Limits in this initial implementation: 10 MB per file, 250 MB of files and 8 MB of structured state per thread; direct WebRTC depends on network policy and falls back to relay; one relay process in the initial Server deployment. Revocation prevents further sync and execution requests; it cannot erase files someone already downloaded. There is no automatic owner takeover if its machine is lost.
MIT OR Apache-2.0. See LICENSE files in this repository.
The installed runtime still reports upstream DSH/MCP and source-map security advisories. The October 22 audit also reports Hono/Nodemailer findings; recommended fixed releases currently return npm 404s. These findings remain unresolved and must be rechecked when patched packages become available.
Bees Credits supports the Server-approved model catalog and a reasoning-effort selector in AI Models. Organization work uses its shared purchased-credit balance; personal work uses the executing user’s personal balance. Organization owners/admins manage token purchases and auto-renew. A run keeps its organization wallet even if you switch organizations in the UI. Update the Server with migrations 013–015 before using organization credits; the Client refuses to substitute a personal wallet on an older Server.