# SweetHive — How SweetHive works — and how to get the most out of it. One markdown file with the whole guide — give it to ChatGPT, Claude or any assistant and ask how to use SweetHive and boost your activity. Source: https://docs.sweethive.com/en/ (generated from the official SweetHive documentation). --- # What SweetHive is SweetHive is a workspace where every place of work has its own context and its own scope. Instead of one big chat, information is organised into a **tree of contexts**, and who sees what is decided by **groups** - not by long recipient lists. ## The three building blocks - **Hive** - a workspace (a company, a project, a school, a museum, a family). Everything lives inside a hive. - **Context** - a node inside a hive. Contexts form a tree: a context can contain sub-contexts, as deep as you need (e.g. *WEREA SRL → Administration → People → Payroll*). - **Group** - a set of people. Groups are attached to contexts and gate visibility: you see a context only if one of your groups is **active** there. ## How visibility flows Visibility flows **down** the tree: access to a context also covers the contexts within it. A message you write in a context, addressed to a group, is visible to that group in that context and everything below it - never wider. > **The golden rule:** nothing is visible to someone unless a group they belong to is > active on that context. This is what keeps mixed-trust audiences (staff, partners, > clients) safely separated in one hive. ## What lives in a context Beyond messages, each context aggregates its content into built-in apps - **Gallery** (images and video), **Notes**, **Tasks**, **Planner** (events), **AnyDocs** (files and links) - and can host custom apps installed by an admin. Everything obeys the same visibility law. ## Where AI fits SweetHive is built to work with AI assistants: you can connect your own agent (Claude, an OpenClaw-class agent, or any MCP-capable assistant) with a scoped token that never exceeds your own visibility, chat with it from inside SweetHive, and download this whole guide as a single markdown file to teach any AI how SweetHive works - see [Use SweetHive with AI](/en/use-sweethive-with-ai/). --- # Quick start ## Sign in Go to [sweethive.com](https://sweethive.com) and sign in with your email (or phone) and password. SweetHive uses a single sign-on across the whole product family, so the same account works on the web app, the mobile apps and the satellite products. On **iOS and Android** the SweetHive app signs you in with the same credentials - see [Mobile apps](/en/mobile/). ## The home page: My SweetHive After signing in you land on **My SweetHive**, your personal dashboard: - **Invitations** - hives you've been invited to; accept to join. - **Hives** - every hive you belong to, with **Create new** to start your own. - **Contexts** - quick access to the contexts you use. - **Connectors** - external services (Gmail, Google Calendar, Google Drive, …) you've connected; see [Connectors](/en/connectors/). - The **activity feed** - messages shared with your groups across all your hives. ## Finding your way around - The **top bar** shows where you are (hive → context breadcrumb) and hosts **Write a message** and **search**. - The **icon rail** on the left switches between the areas of the current hive: Contexts, Groups, People, Apps, Agents, Connectors, Notifications. - The **message panel** is docked beside the content and always follows the context you're in: it shows the feed of the current context subtree. ## Your first steps 1. **Join or create a hive** - accept an invitation, or [create a hive](/en/create-a-hive/) with the guided wizard. 2. **Open a context** and read its dashboard: description, sub-contexts, active groups, apps, people. 3. **Write a message** - pick the context and the target groups, attach what you need, send. See [Messages](/en/messages/). 4. **Install the mobile app** - SweetHive is on the App Store and Google Play; see [Mobile apps](/en/mobile/). ## Languages SweetHive speaks **English, Italiano, Français, Deutsch and Español**. Set your language in *Settings → Profile → Preferences* - the app (and links to these docs) follow it. --- # Create a hive Anyone can create a hive. The person who creates it becomes its first admin, with an **Admin group** created automatically. Creation is a **guided wizard** that helps you design a complete environment - contexts and groups - before anything is created. Start from **My SweetHive → Hives → Create new**. ## Step 1 - Create Choose what you want to build: **Company**, **Team**, **School** or **Project** on SweetHive - or a **Museum** (AerariumChain) / **Academy** (WiredExperience) on the satellite platforms. Your choice tunes the rest of the wizard. ## Step 2 - Plan Pick who owns the hive: - **Personal** - the hive lives on your personal account and its (free) plan. - **Organisation** - the hive belongs to one of your organisations and runs on the organisation's plan. See [Settings](/en/settings/) for creating organisations and managing plans. ## Step 3 - Template Pick a starting structure from the template catalog for your cluster, or start **Blank**. Your purpose from step 1 preselects a matching template when there is one. A template describes a ready-made environment: the context tree, the groups, and which groups are active where. ## Step 4 - Environment This is the heart of the wizard: a full **tree editor** where you shape the environment before it exists. You can: - **add, rename and delete contexts**, nested as deep as you need; - **add, rename and delete groups**; - **toggle which groups are active in each context** - deciding, node by node, who will see what. Take your time here: a well-designed tree means visibility takes care of itself later. ## Step 5 - Details Name the hive, add an optional description, and import a **cover image** - drag to reposition, zoom with the slider; SweetHive resizes it for you. If the environment you built is worth reusing, tick **“save this environment as a reusable template”** and it joins your template catalog for next time. **Create** applies the whole edited tree in one atomic operation - contexts, groups and activations come to life together, and you land in the new hive as its admin. > **Tip:** design groups around *audiences* (Staff, Suppliers, Clients, Board), not > around org charts. You'll target messages at audiences every day. ## Leave or transfer a hive From **My Hives**, open the **...** menu on any hive tile. - **Leave hive** removes you from the hive. You lose access to it and its contents; the hive and everyone else stay. The **owner** cannot leave - transfer the hive or delete it instead. - **Transfer hive** (owner only) hands ownership to someone else. You can transfer to: - **another admin of the hive** - they receive a request and must **accept** it before ownership moves; - **one of your organisations** - applied immediately, so the organisation's plan, members and storage take over. Incoming transfer requests appear in **Invitations**, where you accept or decline them. --- # Manage your hive Every hive has one **owner** and any number of **admins**. From **My Hives**, open the **...** menu on a hive tile for **Leave** and **Transfer**; the owner-only **Delete** lives inside the hive's own **Dashboard**, under a red "Danger zone". These actions are deliberately careful - deleting a hive asks you to type its name to confirm. ## Transfer a hive Only the **owner** can transfer a hive, and only to: - **another admin of the hive** - they receive a request and must **accept** it before ownership moves; or - **one of your organisations** - applied immediately, so the organisation's plan, members and storage take over. If the person you have in mind is not listed, it is because a hive can only be handed to an existing **admin**. **Invite them to the hive as an admin first** (see [People and invitations](/en/people-and-invitations/)), then transfer - or transfer to an organisation you administer. Incoming transfer requests appear in **Invitations**, where you accept or decline them. ## Leave a hive **Leave hive** removes you from the hive: you lose access to it and its contents, while the hive and everyone else stay. You can be invited back later. The **owner cannot leave** - a hive always needs an owner. If you own it, SweetHive explains this and offers to **transfer** it instead. Hand ownership to another admin (or delete the hive) first, then you can leave. ## Delete a hive Deleting a hive removes **everything** in it - every context, message, file and membership - for **everyone**. Only the **owner** can do it, from the hive **Dashboard → Danger zone → Delete this hive**. To prevent mistakes you must **type the hive's name** to confirm. Deletion is **not immediate**. It runs with a **30-day grace period**: - the hive is **locked read-only** straight away - no new messages or invitations; - **every admin is emailed** and **every member is notified** in the app; - during those 30 days **any admin can cancel** the deletion - from the read-only banner on the hive, or from the link in the email (no sign-in needed); - after 30 days the hive and all its content are **permanently deleted**. This cannot be undone. > **Changed your mind?** While the hive is scheduled, open it and use **Cancel deletion** > on the banner, or click the cancel link in the email. The hive becomes active again > right away. --- # Contexts Contexts organise a hive into a tree. Every context has its own dashboard, its own feed, its own apps - and its own audience, decided by the groups active on it. ## Create a context Only a hive admin can create contexts - the **Create new** button appears on the context dashboard when you have admin rights there. 1. Open the context you want to create inside (or the hive root). 2. In the **Contexts inside** card, choose **Create new**. 3. Optionally import and crop a cover image. 4. Name it, add a description, then **Create**. The new context opens automatically. A new context inherits the hive's **Admin** group, so admins can immediately manage it. Activate member groups to open it to more people. ## The context dashboard Opening a context shows: - **Description & cover** - what this place is for. - **Contexts inside** - the sub-contexts you can see. - **Active groups** - who can see this context. Admins activate and deactivate groups here; see [Groups](/en/groups/). - **Apps** - the built-in apps plus any custom apps installed here; see [Built-in apps](/en/built-in-apps/). - **People** - who is effectively in this context, via its active groups. The docked **message panel** beside the dashboard shows the feed for this context *and everything below it* - messages posted deeper in the tree surface here too, and you can filter them (see [Messages](/en/messages/)). ## Moving around The **breadcrumb** in the top bar shows the path from the hive root to where you are; **Go UP** climbs one level. The icon rail's **Contexts** item lists the current context's subtree. > **Design tip:** a context is a *place*, not a topic label. If a set of information > has its own audience or its own lifecycle - a project, a department, a client - it > deserves its own context. --- # Groups A group is a named set of people (e.g. *Admin*, *Founders*, *DevGroup*, *Suppliers*). Groups belong to a hive and are attached to contexts to grant visibility. They are the only thing that decides who sees what. ## Create a group 1. In a hive, open **Groups** from the icon rail. 2. Choose **Create**, give the group a name and description. 3. Add people to the group. ## Edit who is in a group From the **Groups** page, open a group and choose **Edit users** - a two-column editor shows who is *in* the group and who else is in the hive. Move people in and out and **Save**; their visibility across every context where the group is active updates immediately. You can also work from the person's side: on the **People** page, use a person's **⋮ → Change groups** to adjust all their memberships at once. ## Activate a group on a context A context shows its **Active groups** on the dashboard. Activating a group on a context is what makes that context (and everything below it) visible to the group's members. Deactivate a group to remove that access instantly. > Because visibility flows down, activate a group **as high in the tree as the access > should reach - and no higher.** ## Everyday patterns - **Admin group** - created automatically with the hive; active everywhere admins need to manage. - **One group per audience** - Staff, Clients, Suppliers, Board. Messages are then targeted by audience with one chip. - **Project circles** - a group per project team, active only on the project's context; the rest of the hive stays invisible to them. - **Temporary access** - activate a group for the duration of an engagement, then deactivate it. No cleanup of individual permissions needed. --- # People & invitations Open **People** from the icon rail to see who is in the hive. From here you invite new people and manage the ones already in. ## Invite someone 1. Choose **Invite people** and send an invitation by email. 2. The invitee sees it in **My SweetHive → Invitations** and accepts to join. 3. Once in, add them to the right [groups](/en/groups/) - until then they only see what the default membership allows. ## Manage a person - **⋮ → Change groups** - adjust exactly what they can see, across all groups in one dialog. - **Remove from hive** - revokes all their access at once. ## What a new member sees Nothing, until a group they belong to is active on a context. This is by design: you can safely invite a client or an external collaborator into the hive, and they will only ever see the contexts you open to their group. > **Tip:** invite first, then place. It's normal for a new member to see an almost > empty hive until you've added them to their groups. --- # Messages Messages are always written **in a context** and addressed **to one or more groups** - that is how SweetHive keeps scope honest. The message (and any attachment) is visible to those groups in that context and below, never wider. ## Write and share 1. Open the context you want to post in. 2. Choose **Write a message** (top bar) or **Write** on the context dashboard. 3. Confirm the context and pick the target groups shown as chips. 4. Type your message. Add images, files, a link, a task, an event or a note from the attachment picker. 5. **Send.** Recipients see it in their activity stream; you can see who has seen it. **Reply** to keep a thread together. A message can only be seen by people who share one of its groups - there is no way to leak it wider. ## Content and attachments - **Images and videos** also appear in the context's **Gallery** app. - **Files and links** appear in **AnyDocs**. Click any content to open it full-screen, with the original message beside it. - **Notes** are documents you can edit; they appear in the **Notes** app. - **Tasks** and **events** land in **Tasks** and **Planner**. - Content from your [connectors](/en/connectors/) - a Gmail message, a calendar event, a Drive file - can be shared into a context as a rich card. ## Search and filter the feed The message panel follows the context you're in and shows the feed of its whole subtree. To find things: - **Search messages** from the top bar searches the text of the feed. - **Filters** narrow the feed by: - **date range** - from/to; - **author** - only messages from selected people; - **content type** - messages with images, files, links, tasks, events or notes; - **sub-contexts** - include the whole subtree or only the current context. Filters combine, and the active filter is always visible above the feed - clear it with one click. ## Notifications New messages for your groups raise in-app notifications (the **Notifications** page collects them all) and **push notifications** on the mobile apps. Tapping a push opens the exact message in its context. --- # Apps in a context Every context aggregates its content into **built-in apps**, and a hive admin can install **custom apps** on top. Apps see data through the same scope law as everything else: only what the person using them can see, never beyond it. ## The built-in apps | App | What it collects | |---|---| | **Gallery** | every image and video posted in the context subtree | | **Notes** | editable documents created from the composer | | **Tasks** | tasks attached to messages, with status | | **Planner** | events attached to messages, on a calendar | | **AnyDocs** | every file and link, in one searchable place | Open them from the **Apps** card on the context dashboard. Content opens full-screen with the original message beside it, so nothing loses its context. ## Install a custom app (admins) 1. Open the context and find the **Apps** card on the dashboard. 2. Choose **Add app** (visible to admins). 3. Pick an app from the catalog and choose **Add**. It appears under *Installed apps*. 4. Open it from the Apps card - **embedded** apps render in place; **external** apps open in a new window (or the in-app browser on mobile). Remove an app anytime from its menu - its access stops immediately. ## Professional app families SweetHive also hosts production app families used by thousands of organisations - for example the **Safety-BI** document and training registries (**DocBI**, **Document BI**, **Records**, **DBI Global**), used for per-employee certificates, context document management and employee records. If your organisation uses them, they appear in the context's Apps card like any other app. Want to build your own app? See the [developer guide](/en/build-an-app/). --- # Connectors **Connectors** bring your external services into SweetHive so their content can be shared into contexts with the same group-based visibility as everything else. Open the hub from **My SweetHive → Connectors** or the **Connectors** item in the icon rail. ## Available today - **Gmail** - browse your inbox (read-only) and share an email into a context as a rich card. - **Google Calendar** - browse your upcoming events (read-only) and share an event into a context. - **Google Drive** - browse your files (read-only) and share a file card into a context. Drive shares the same Google connection as Gmail and Calendar. More connectors - Outlook, Dropbox, OneDrive, Slack, Telegram, Trello, Asana, Jira, GitHub - are on the roadmap and appear in the hub as **coming soon**. ## Connect Google 1. Open **Connectors → Gmail** (or Google Drive). 2. Choose **Connect** - a Google consent window opens; approve the read-only scopes. 3. Your mail / events / files appear in the connector page, read-only. **Privacy by design:** - Access is **read-only** - SweetHive never sends mail, creates events or modifies files on your behalf. - Your Google tokens are stored **server-side only** and never reach the browser. - Disconnect at any time from the connector page; access stops immediately. - If a new capability is added to the Google connector (as Drive was), you'll simply be asked to reconnect once to grant the extra read scope. ## Share into a context Every mail, event or file in a connector has a **Share** action: 1. Choose **Share** on the item. 2. Pick the **hive → context → groups** in the share dialog. 3. Send - the item lands in the context feed as a rich card (subject/sender for mail, title/time for events, name/type for files), visible only to the groups you targeted. This is the bridge between your personal tools and your team's contexts: instead of forwarding an email, you *place* it where it belongs. --- # Settings Open **Settings** from your avatar in the top bar. Settings has three main sections today - Profile, Plan & billing, and Organizations - with more (orders, providers) on the way. ## Profile Everything about you: - **Identity** - name, avatar (upload and crop), contact details, address, social links. - **Preferences** - including your **language** (English, Italiano, Français, Deutsch, Español); the whole app follows it instantly. - **Password** - change it with your current password. - **Visibility** - each profile field carries its own visibility setting, so you decide what other members can see. Each card saves independently - edit, then **Save** on that card. ## Plan & billing Your personal account carries its own plan (free by default); each **organisation** carries its own - normally paid - plan. Hives and resources are assigned to you *or* to an organisation. - **Current plan** - with live member and storage meters. - **Available plans** - upgrade via secure Stripe checkout; billing can also run by bank transfer where enabled. - **Payment methods** - saved cards, default card, remove. - **Billing data** - invoice details (company name, VAT, address) used on receipts. - **Payment history** - every payment with downloadable receipts and invoices. ## Organizations An organisation is a legal/billing entity that can own hives and resources. - **Create** an organisation (pick a unique username; it gets its own business cluster). - **Profile & invoicing** - the organisation's identity and billing data. - **Admins** - two admin roles: *global* admins manage everything, *finance* admins manage billing. Add or remove either. - **Plan & quota** - the organisation's plan, member/storage usage, its own cards and payment history. When you [create a hive](/en/create-a-hive/) on an **Organisation plan**, it's the organisation that owns it - and its plan, members and storage that count. ## Delete your account You can permanently delete your account from **Settings > Profile**, in the "Danger zone". - Deletion is a **staged, multi-step** action: you confirm the consequences, optionally **download a copy of your data** first, enter your password, type a confirmation word, and confirm once more. - It does not happen instantly. Your account enters a **grace period** (14 days by default) during which it is deactivated but can still be **restored**. We email you a link to cancel the deletion, in case the request was not yours or you change your mind; you can also restore it by signing back in during the grace period. - After the grace period the account is permanently deleted: your personal data is removed or anonymized, and content you posted in shared hives stays but is no longer attributed to you. Records we must keep by law (such as invoices) are retained. - If you **own an organisation**, transfer or close it first. If you **own a hive with other members**, transfer the hive (see [create a hive](/en/create-a-hive/)) before deleting. --- # Mobile apps SweetHive is available as a native app for **iOS** and **Android**, with the same account and the same data as the web app. ## Download - **iPhone / iPad** - search for **SweetHive** on the **App Store**. - **Android** - search for **SweetHive** on **Google Play**. Sign in with the same email (or phone) and password you use on [sweethive.com](https://sweethive.com). Everything works the same as on the web: contexts, groups, messages, apps and connectors follow the same visibility rules everywhere. --- # Use SweetHive with AI SweetHive is designed to work *with* your AI assistant, whichever one you use. There are two levels: teach an AI **about** SweetHive, and connect an AI **to** your SweetHive. ## 1. Teach your AI about SweetHive (the .md guide) This entire documentation is available as **one markdown file per language**: **[Download the SweetHive guide (.md)](/downloads/sweethive-guide.en.md)** Give that file to ChatGPT, Claude, Copilot or any assistant - attach it to a chat, a project, or a custom assistant's knowledge - and it instantly knows how SweetHive works: hives, contexts, groups, visibility, messages, connectors, settings, apps. Then ask things like: - *“Based on this guide, design a hive structure for my architecture studio with staff, external consultants and clients.”* - *“What groups should I create so suppliers see logistics but never pricing?”* - *“Draft the weekly update message for my DevGroup and tell me which context to post it in.”* - *“How can my team use connectors to stop forwarding emails around?”* - *“Audit this plan: who would see what if I activate ‘Clients’ on the project root?”* Every page of this site is also available as raw markdown - add `.md` to any article URL (e.g. `/en/messages.md`) - and AI crawlers can discover everything via [`/llms.txt`](/llms.txt). ## 2. Connect an AI to your SweetHive Beyond knowing *about* SweetHive, your assistant can securely read (and, if you allow it, post into) your actual hives: - [Connect an agent](/en/connect-an-agent/) - issue a scoped access token from SweetHive; works with Claude Desktop, Claude Code, OpenClaw-class agents and any MCP-capable assistant. - [Chat with your agent](/en/chat-with-your-agent/) - talk to your connected agent from inside SweetHive. Then your questions stop being hypothetical: - *“What changed in Project A this week?”* - *“Summarise the open tasks in Administration → People.”* - *“Draft a status update for the DevGroup in Gigapixel.”* ## Boost your activity - a recipe 1. **Download the guide** above and give it to your assistant once. 2. **Design with it** - let it propose your context tree and groups; build the result with the [hive creation wizard](/en/create-a-hive/). 3. **Connect it** with a read-only token to your working contexts. 4. **Make it a habit** - morning catch-up (“what's new for me?”), weekly summaries, drafted updates you approve before posting. Your AI knows the method; your SweetHive holds the facts - scoped, safe and always under your control. --- # SweetHive Agents Node The **SweetHive Agents Node** is a desktop app for macOS and Windows that runs your SweetHive agents **on your own computer**. Your agents answer with AI models executed locally - prompts and content never leave your machine during inference - and the app can also connect assistants like **Claude** or **ChatGPT** to your SweetHive content through MCP. > Using OpenClaw? It keeps working as an alternative runtime: it reads the same > config bundles. The Agents Node simply makes everything one guided install. ## Install 1. Download the app: - [macOS (Apple Silicon)](https://downloads.sweethive.com/agents-node/mac/SweetHive-Agents-Node-arm64.dmg) - [macOS (Intel)](https://downloads.sweethive.com/agents-node/mac/SweetHive-Agents-Node-x64.dmg) - [Windows](https://downloads.sweethive.com/agents-node/win/SweetHive-Agents-Node-Setup.exe) 2. Open it, review and **accept the terms**. 3. **Sign in with your SweetHive account** (the same email and password as the web app). The app keeps itself up to date automatically. The macOS builds are signed and notarized by Apple, so they open without warnings. ### Updates - When a new version is out, a banner at the top of the app says **A new version is available** with an **Update** button. - From SweetHive web you can update a node remotely: **My agents** shows an **Update** button next to each node that is behind, and the **My SweetHive** dashboard shows a banner. The node downloads the new version and restarts within a few minutes (version 0.2.15 and later). - Older versions update by hand: *Settings, Check for updates*, then *Restart and update*. ## Add context agents A *context agent* is a scoped connection to the hives and contexts you choose - it can never see more than you can. You can add one from either side, and both stay in sync: - **From the app** - *Context agents → New context agent*: name it, pick the hives, choose a capability and expiry. It appears in SweetHive → **My agents** instantly. - **From SweetHive web** - *My agents → Connect an agent*: create the token, download the config bundle and import it in the app (*Context agents → Import config bundle*). Chat with your agents from **My agents** in SweetHive - replies are generated on your computer. See [Chat with your agent](/en/chat-with-your-agent/). ## Local models The AI runtime ships **embedded in the app** - nothing else to install. The *Local models* tab shows a curated catalog organised by machine size, with a recommendation for **your** computer (current families such as Qwen, Gemma, Granite, Nemotron and Mistral): one click installs a model (with live progress), one click uninstalls it, and installed models show a badge. Models that are no longer in the catalog appear only if they are already installed, at the bottom under *Previous models on this computer*. If you uninstall a model that one of your agents is using, the app asks what to use instead (the default model or another installed one), so no agent is left without a model. In *Settings → Storage folders* you can choose where models, temporary files and tool libraries are stored. ## Render workers (SweetReach) The node can also run **render workers**: plug-ins that turn a marketing brief into a finished video for **SweetReach**, SweetHive's marketing app. In the *Marketing* tab, connect the node to the marketing backend with your node secret, then install a worker: - **HeyGen** - photoreal AI avatars via the HeyGen API. No GPU needed; paste your HeyGen key. The node renders the video, downloads it locally, then uploads the finished file to SweetHive storage. - **Local avatar (GPU)** - a talking-head avatar rendered entirely on your GPU, offline, with a local voice. Best on a workstation or server. Video jobs reach the node as SweetHive [jobs](workflows-and-jobs): only a node with a ready worker (a HeyGen key or a GPU worker) takes them, renders the video with the worker you chose and hands the file back to SweetReach. The script is written separately by the agent connected to the campaign's context (which may run on a different node), so each job runs on the right machine. New workers appear in the catalog without an app update. ## Jobs: workflows and app requests The node runs the steps of your [workflows](workflows-and-jobs) and the requests of SweetHive apps with its local models: reading documents for SweetTimetable, rendering videos for SweetReach, generating and extracting text. It takes the work by itself as soon as SweetHive has something for it: there is nothing to configure app by app. The **Jobs** section of the app shows, in plain words, what the node is doing now (with its progress) and what it did recently, including why something failed (for example a model that is not installed or a document too long for the model). The same list is in SweetHive web under **My agents, Jobs**. ## Reading documents (SweetTimetable) The scans and photos you upload to SweetTimetable become jobs in **My agents, Jobs**, and they are run by your node, by the hive's shared node or by your organization's [Agents Server](agents-server). In SweetTimetable you see the result: the proposed expenses to check in *Upload documents*. - PDFs that contain real text are read directly on the server, with no node needed. - A page with several receipts is read in sections (each motorway toll is its own expense): with a vision model such as qwen2.5vl:7b it takes about two minutes on a recent Mac, and the full transcription arrives after the proposed expenses. - If a job waits, SweetTimetable and My agents tell you what to do: turn the computer on, update the Agents Node, or choose a model that can see images. - Always check the proposed expenses before creating them. ## Connect Claude or ChatGPT The *Connect AI apps* tab turns the node into an MCP server for your assistant - now with **one-click setup**: - **Connect Claude Code** - finds your `claude` CLI and registers the node automatically; open a new session and ask about your SweetHive content. - **Connect Claude Desktop** - writes the entry into Claude Desktop's configuration for you; restart Claude Desktop and the tools are there. - **Developer options** - the JSON snippet and a secret-protected local HTTP MCP endpoint for other clients. ## SweetHive Desktop - chat with your computer The Chat tab includes **SweetHive Desktop**: conversations with the machine itself, organised like a modern AI chat (a titled thread list, *New chat*). Answers come from your default local model and your data stays on the computer; the conversations sync to your account, so you can also open them **from SweetHive web** (*My agents → SweetHive Desktop*) and talk to your computer remotely - it answers within seconds whenever the app is running. ## Privacy & control - Tokens are scoped, expire, and can be revoked anytime from **My agents**. - Secrets are stored encrypted with your operating system's key store. - Model inference runs entirely on your machine. --- # Company agent servers The **SweetHive Agents Server** lets a company run the AI agents of its whole organization **on its own hardware**. One machine, managed by your IT team, hosts the agents of every member of the organization's hives and runs their [workflows and jobs](workflows-and-jobs): nobody installs anything on their computer, and inference never leaves the company network. It is the business alternative to the personal [Agents Node](agents-node): edge computing plus SaaS - collaboration stays in the SweetHive cloud, the intelligence and the data it processes stay on hardware the company owns. > **Organization plans only.** Company agent servers are available on > Organization plans, for the hives the organization owns. The software is > distributed exclusively from the organization settings panel. ## For members: put your agent on the company server If your organization runs an agent server, you will see it in the [Connect an agent](connect-an-agent) dialog as an extra location, next to your personal Agents Node: 1. In SweetHive web, open **My agents** and choose **Connect an agent**. 2. Pick the **company server** as the location (it shows how many agents you can still host there - each member has an allowance set by the organization plan). 3. Create the agent as usual. It installs itself on the company server and comes online within about half a minute. Nothing to download. Your agent works exactly like one running on your own computer: it answers in your agent chats, sees only what you can see, and you can revoke it anytime from My agents. The company server also runs **jobs**: steps of your workflows and requests from SweetHive apps in the organization's hives (for example reading the receipts uploaded to SweetTimetable). You follow them in **My agents, Jobs** like any other job. **Your data stays yours.** On the server, every user's agent runs in its own isolated workspace, encrypted with keys dedicated to that user. Conversations, tokens and memory of different users are never mixed, and the IT console shows operations only - never message content. ## For organization admins: set up a server 1. Open **Settings, Organizations**, pick your organization and go to the **Agent servers** tab (visible to organization admins). 2. **Create a server** and copy its enrollment key - it is shown only once. 3. Choose how to run it (download links in the same tab): - **App for macOS or Windows** - for a Mac mini, a Mac Studio or a Windows workstation. Download the app for your computer (macOS Apple Silicon, macOS Intel, Windows) and install it. - **Docker** - for a Linux server. Download the package, unpack it and start it (see below). 4. The server appears **online** in the tab within a minute. Pull one or more local models and you are done: members of your hives can now choose the company server when they create an agent. ### The app (macOS, Windows) On first launch a short setup asks for: - a **password for the admin console** (at least 10 characters); - the **enrollment key** from the Agent servers tab (you can also add it later in *Settings, Organization*); - whether the console is reachable **only from this computer** or **from the company network** (plain http: on the network put an https proxy in front of it); - where the models run: **on this computer** (the AI runtime is included in the app) or on external Ollama servers, and the default model. > **Save the recovery key.** At the end of the setup the app offers the > **recovery key** (also available later in *Settings, Security*). Keep it > safe: without it, the agents' data **cannot be recovered** on a new or > reinstalled computer. The app lives in the menu bar / system tray, starts with the computer, keeps the computer awake while it serves agents, and updates itself. The macOS app is signed and notarized by Apple; on Windows the installer is not signed yet, so Windows may show a SmartScreen prompt the first time (choose *More info, Run anyway*). ### Docker (Linux) ```bash tar xzf sweethive-agents-server.tar.gz && cd sweethive-agents-server cp .env.example .env # set SH_MASTER_KEY and SH_ORG_NODE_KEY docker compose up -d --build ``` Open the admin console on port 8800, pull a model and you are done. To update, download the new package from the Agent servers tab and run `docker compose up -d --build` again. From the same tab you can see each server's status, version, hosted users and models, and **revoke** a server: it immediately stops receiving new agent installs and jobs; agents already installed keep answering until their tokens are revoked by their owners. ### Updates The **Update** button on a server's row in the Agent servers tab asks the server to update itself: the app downloads the new version and restarts within a few minutes. A Docker install writes the request in its log with the commands for IT. ### Reading documents (SweetTimetable) Receipts and invoices uploaded to SweetTimetable in the organization's hives become jobs: when a member's own computer cannot take them, the company server reads them, so nobody needs the Agents Node for that. Choose a model that can read images in *Settings, Document reading* (the app suggests one for the computer's memory). The SweetTimetable token that servers before version 0.3.0 needed is no longer required. ## Organization policy: agents only on company servers In the Agent servers tab an organization admin can decide that the organization's hives are readable **only by agents running on the company servers**. When the policy is on, members can no longer place agents for those hives on their personal computers, and agents already installed on personal computers stop seeing those hives. ## Limits and privacy - **Per-member allowance.** The organization plan sets how many agents each member can host on the company servers. The wizard shows the allowance and the server enforces it. - **Scoped by construction.** Each agent authenticates with its owner's scoped token: it sees exactly the contexts granted to it, with the owner's own visibility, never more. - **Isolated per user.** Tokens and conversation memory are encrypted per user on the server; data of different users is never mixed. - **Admins manage capacity, not content.** The IT console exposes status, models and counters. It has no access to conversations or messages. --- # Workflows and jobs A **workflow** is a chain of steps that your agents run for you: read the new messages of a context every morning and post a summary, read the documents that arrive and extract the data, answer a webhook from another system. You build it once in SweetHive and it runs by itself. Workflows run **on your own computers**, not in the cloud: on your [SweetHive Agents Node](agents-node) or on your company's [Agents Server](agents-server). The AI models, the documents and the data they process stay on those machines. Everything that runs for you is listed in **My agents, Jobs**: your workflows and the requests coming from SweetHive apps (for example SweetTimetable reading your receipts, or SweetReach rendering a video). ## Create a workflow 1. Open **My agents** and choose the **Workflows** tab. 2. Click **New workflow**. The editor opens with a canvas: - on the left, the list of **steps** you can add; - in the middle, the **canvas** with your steps and the links between them; - on the right, the **settings** of the selected step. 3. Click a step in the list to add it after the selected one. To link two steps, drag from the dot on the right of a step to another step. 4. Choose the **agent** the workflow runs as (top bar). Steps that read or post in your hives use that agent, so the workflow never sees more than the agent can. 5. **Save**. Every change to the steps saves a new version; runs already started keep the version they began with. 6. Press **Run** to try it: each step on the canvas shows its state live (waiting, running, done, failed) and, once finished, its result. ## When a workflow starts Select the first step (the trigger) to choose how the workflow starts: - **Manual** - when you press Run, in the editor or in the Workflows list. - **Scheduled** - at fixed times: every hour, every day at 8:00, Monday to Friday at 9:00, or any schedule you write (cron) in your time zone. - **Hive event** - when there is a new message, file, task, event or email in a hive (optionally in one context). - **Webhook** - when another system calls the workflow's URL. The secret is shown once: copy it when you create it. - **App event** - when a connected app emits an event (for example a new lead in SweetCRM). You can pause a workflow at any time with its **Active** switch. ## The steps | Group | Steps | |---|---| | SweetHive | **Read context** (messages, files, tasks of a context), **Post to context** | | AI on your computer | **Generate text**, **Extract data** (text to structured data), **Read document** (PDF, scans and photos to text and data), **Render video** | | Integrations | **HTTP request** (https only; private networks are blocked) | | Data | **Set values**, **Map list**, **Filter list** | | Flow | **If** (two branches), **Switch** (one branch per case), **Wait** | A step can use the results of the previous ones. In any text field, insert a variable with the buttons under the settings, for example `{{ $steps.summary.output.text }}` (the text generated by the step called *summary*) or `{{ $trigger }}` (what started the workflow). There is no code to write. ## Where the steps run Each step runs on one of your computers: - by default it stays on the **same computer as the previous step** (the model is already loaded, the files are already there); - it moves to **another computer** when it needs something the first one does not have: a model that sees images, a larger context, a render worker. You can also let a step run on **any available computer** (*Where it runs* in its settings). If none of your computers can run a step right now, the job waits and tells you why (for example *Waiting for one of your computers: open the SweetHive Agents Node*). It starts by itself as soon as a suitable computer is online. ## Follow your jobs **My agents, Jobs** lists what is running and what ran, newest first. Each job shows who started it (a workflow or an app), how many steps are done, which computer is running it and, when something goes wrong, the reason in plain words: the model is not installed, the document is too long for the model, the file link expired, the computer stopped responding. - **Cancel** stops a job that is waiting or running. - **Retry** runs a failed or cancelled job again. - Open a job to see every step, the computer and model it used, how long it took and its result. When the problem is on the computer (a missing model, a context too small, the computer turned off), the job does not use up its attempts: it moves to another computer or waits. When the problem is in the input (an unreadable document, an answer the model could not format), it is retried once and then reported. The SweetHive Agents Node shows the same list in its **Jobs** section: what it is doing now and what it did recently. ## Privacy - A workflow runs **as one of your agents**: it sees only the hives and contexts that agent can see, and it can post only if that agent can post. - AI steps run **on your computers** with local models. - Files passed between steps are kept for 7 days and then deleted. Links to documents sent by apps are never shown in the job lists. --- # Connect an agent You can connect a local AI assistant - Claude Desktop, Claude Code, an OpenClaw-class agent, or any MCP-capable agent - to SweetHive. It connects with a **scoped access token** that never exceeds what you can see, and that you can revoke at any time. ## Create a connection 1. Open **My agents** from the home rail (or *Settings → Connected agents*). 2. Choose **Connect an agent**. 3. Name it, pick the **hives and contexts** it may access, choose a **capability** and an **expiry**. 4. Create the token. **Copy it (shown once)** or download the config bundle. 5. Register the connector with your local agent using the bundle - see [MCP connector setup](/en/mcp-connector/). ## Where the agent runs When you create the agent you choose where it runs: - **Your SweetHive Agents Node** - the app on your computer, with local models. The agent answers while the computer is on. - **The company server** - if your organization has an [Agents Server](/en/agents-server/), it shows up as a destination, with how many agents you can still host there. Nothing to install: the agent lives on the server, in an isolated space that is yours alone. - **Bundle to import** - you download the configuration and import it into a compatible agent yourself. > **Organization rule.** An organization can decide that its hives are > readable **only by agents on the company servers**. If you pick a context of > that organization, SweetHive tells you and offers the company server; agents > already installed on a personal computer stop seeing those hives. ## Capabilities | Capability | The agent can | |---|---| | **Read** (default) | read items and search in its scope | | **Read + draft** | also prepare drafts for you to send | | **Read + post** | also publish posts and replies as you - it confirms the exact text with you in chat first | ## What stays safe - The token's scope is **intersected with your live visibility on every request**. Leave a group, and the token loses that access at the same instant. - **Read-only is the default.** Posting needs a Read + post token, and the agent confirms the exact text with you in the chat before anything is published. - Anything a connected agent posts is attributed **“via you”** and obeys the same group targeting as any message. - **Revoke** a token in one click from its card - access stops immediately. - Every token's card shows when it was last used and how much it has read, and hive admins can allow, restrict to read-only, or block external agents on their hive entirely. > Your agent runs **outside** SweetHive. Anything the token can read, treat as being > on your machine - so scope it tightly: the contexts it needs, nothing more. ## See your agents at work The **My agents** page lists every token with its scope, capability, expiry and a live **online** indicator (the agent has checked in recently). From a context, you can also see which of your agents currently cover it. --- # Aristeo, the hive keeper Aristeo taught humanity to become hivekeepers. Today **Aristeo™** is SweetHive's **Consultant Agent**: an AI consultant for hive admins. Instead of building your hive by hand, you describe your organisation and the agent designs a good structure with you, then builds it: it creates contexts and subcontexts, sets up groups by role, invites the right people into the right groups, and posts a short welcome message in each new space. It keeps helping you as the organisation grows. It is the same connected-agent technology as your other SweetHive agents, with one extra ability: **admin**. That ability lets it build the hive **for you**, and it is always bounded - every action runs as you and only where you are a real hive admin. ## What it does for you - **Understands your organisation first.** It asks what kind of hive this is (company, team, school, project, condominium...), who the audiences and roles are, and what needs its own space. - **Proposes a structure.** It grounds the proposal in ready-made templates and in SweetHive's own best practices: a context is a place not a topic, groups are built around audiences (Staff, Clients, Suppliers, Board), and a group is activated only as high in the tree as the access should reach. - **Builds it with you, one piece at a time.** It creates a context, then its groups, then activates them where they belong, telling you each step so you can follow along and correct course early. - **Places people by role.** It invites new people by email and existing members by name, into the groups that match their role, and reminds you that a new person only gains access after they accept. - **Welcomes everyone.** When it creates a context or activates a group, it posts a short "here is where you can write for..." message so members know what each space is for. - **Helps it evolve.** Later it can add a project space, give a supplier temporary access, move someone who changed role, or save a good design as a reusable template. ## How to get one There are two easy ways: 1. **When you create a hive.** In the hive-creation wizard, on the step where you pick a template, choose **Consultant Agent** instead. SweetHive creates a blank hive and hands off to the agent so it can structure it with you. 2. **From My agents.** Connect an agent (see [Connect an agent](connect-an-agent.md)) and choose the **Consultant Agent** capability, scoped to the hive you want to build. Install it on your [Agents Node](agents-node.md) or a connected assistant. Because Aristeo builds real structure, it is available where you are an admin of the hive. You always stay in control. ## How a session goes A typical conversation looks like this: 1. You: "I need to organise my architecture studio." 2. The agent asks a couple of questions about your teams, clients and projects. 3. It proposes a structure - for example an internal space for partners and staff, plus one space per project with a Client group and a Suppliers group that see only that project. 4. You approve, and it builds it step by step, posting a welcome message in each space. 5. It offers to invite people and places each one in the right group after you confirm exactly who and where. ## Safety - Aristeo's proposals are AI-generated: they may be inaccurate or incomplete, so review each step before you approve it. You remain responsible for your hive's structure, permissions and invitations, as set out in the [Terms of Service](https://sweethive.com/terms/). - The agent acts **as you**, with your identity and your rights. It can never do anything you could not do yourself. - Building is only possible where you are a **hive admin**; every action is re-checked on the server. - Inviting people and posting messages are visible to real people, so the agent always shows you exactly who and what, and waits for your explicit yes before sending. ## See also - [Create a hive](create-a-hive.md) - [Groups](groups.md) - [People and invitations](people-and-invitations.md) - [Connect an agent](connect-an-agent.md) --- # Chat with your agent Once an agent is [connected](/en/connect-an-agent/), you don't have to leave SweetHive to use it: the **Chat with agent** app gives you a direct conversation with it. ## Where to chat - From **My agents** - open the chat on any of your connected agents. - From a **context** the agent covers - the banner shows it connected, with a chat popup one click away. - From the **Agents Node app** on your computer. It is **one conversation per agent**: wherever you open it, you continue the same thread. ## How it works - You write a message; your agent confirms it picked it up right away (you see a typing indicator while it works) and the reply is generated **on your own computer** by the Agents Node - the green dot means it's connected. - The agent replies **in its own voice, to you only** - a chat reply is not a post into the context feed. - If the agent has a **Read + post** token, it can publish real posts and replies into its contexts **as you**. It always shows you the exact text and waits for your yes in the chat before publishing; posting respects your group targeting. - Your agent can also **read the files attached to messages** (PDFs, scans, photos, text files up to 20 MB): ask about a document and it opens it. Scans and photos are read by a local model that sees images, so the file never leaves your computer (or your organisation's agents server). Office files and external links (Drive, YouTube) are not read yet. > Want to talk to your **computer** rather than a context agent? See *SweetHive > Desktop* on the [Agents Node](/en/agents-node/) page - same chat, local models, > reachable remotely. ## Good things to ask - *“Catch me up on this context since yesterday.”* - *“What tasks are still open in Project A?”* - *“Draft a short update for the DevGroup about the release - I'll review it.”* - *“Which contexts had the most activity this week?”* - *“What does the invoice attached to Marco's last message say?”* > The chat is bounded by the agent's token: it can only discuss what its scope - > intersected with **your** live visibility - allows it to see. --- # SweetHive & the EU AI Act > **AI by design. Governance by design. Privacy by design.** SweetHive was designed from the ground up as an AI-native collaborative platform - not a traditional collaboration tool with AI added later. Its architecture aligns naturally with many core principles of the **European Union AI Act (Regulation (EU) 2024/1689)**: governance, human oversight, security, privacy, and controlled access to information. Compliance ultimately depends on the specific AI models and use cases each organization deploys. What SweetHive provides is a technical foundation that significantly simplifies AI Act compliance. ## AI scoped by design The AI Act encourages organizations to minimize unnecessary access to data and reduce the potential impact of AI systems. SweetHive implements this principle at its architectural core. Every AI agent operates inside a strictly defined scope: - only the hives, [contexts](/en/contexts/) and sub-contexts explicitly granted; - only information already visible to the requesting user; - only for the capabilities assigned to its token. On every request, the effective permissions are the **intersection** of: - the user's current permissions; - the token's configured scope. An AI assistant can therefore **never access information beyond what its owner can currently see**. If a user loses access to a context or [group](/en/groups/), every connected agent loses the same access instantly - no token regeneration required. ## Principle of Least Privilege Every connection to SweetHive follows the **Principle of Least Privilege**, a fundamental security principle recommended across European cybersecurity and AI governance frameworks. Agents receive only the minimum permissions needed for their task. Available capabilities are: - **Read** - **Read + Draft** - **Read + Post** Organizations decide which capabilities are allowed within each hive, and administrators may restrict or completely disable external AI agents. See [Connect an agent](/en/connect-an-agent/) for how capabilities and scope are assigned. ## Human Oversight A key requirement of the AI Act is that humans remain in control of AI-assisted decisions and actions. SweetHive is designed around this principle. An agent can draft messages, summaries or reports, but **publishing content always remains under human control**. For agents with **Read + Post** capability: - the exact message is shown to the user; - publication requires explicit confirmation; - every published message is attributed as being sent **via the user**. This is a true **human-in-the-loop** workflow, not autonomous publishing. ## Privacy by Design Privacy is embedded throughout the platform: - scoped access tokens; - immediate token revocation; - live permission evaluation; - read-only connectors by default; - encrypted secret storage; - server-side credential management; - optional local AI inference through [SweetHive Agents Node](/en/agents-node/). When local models are used, prompts and data remain on the user's computer during inference - significantly reducing privacy risk and data transfers. ## Secure AI connections SweetHive exposes its AI capabilities through secure, MCP-compatible connectors. Every AI connection uses: - scoped tokens; - configurable expiration; - revocation at any time; - capability-based permissions; - continuous permission verification. A leaked token never exposes an entire account. Its reach stays limited to the configured scope, the owner's current permissions, and the assigned capabilities. ## Transparency Users always know: - which AI agents are connected; - which contexts they can access; - which capabilities they hold; - when they were last used; - whether they are currently online. Organizations retain full visibility of, and control over, connected AI systems. ## Auditability SweetHive provides accountability features that support governance requirements: - last token usage; - capability information; - expiration dates; - online status; - one-click token revocation; - attribution of AI-generated posts. These mechanisms help organizations build auditable AI workflows and demonstrate operational control. ## Context-aware security Unlike traditional chat systems where an AI often receives access to large collections of documents, SweetHive organizes information into hierarchical contexts protected by groups. Visibility always flows through the organizational structure. This naturally limits AI exposure and dramatically reduces accidental information leakage. The result is an AI system that understands organizational context **without** requiring unrestricted access to organizational knowledge. ## Alignment with the EU AI Act SweetHive is engineered to support many of the principles promoted by the European AI Act: | AI Act principle | SweetHive implementation | |---|---| | Data minimization | Scoped contexts and group-based visibility | | Human oversight | User confirmation before AI publishing | | Least privilege | Capability-based scoped tokens | | Transparency | Visible connected agents and permissions | | Accountability | Token tracking and AI attribution | | Privacy by design | Local inference, scoped access, secure connectors | | Security by design | Dynamic permission enforcement and immediate revocation | ## Compliance notice The European AI Act regulates the **deployment and use** of AI systems, rather than collaboration platforms themselves. SweetHive provides an architecture that supports AI governance and regulatory compliance, but the obligations applicable to a specific deployment ultimately depend on: - the AI models being used; - the intended use case; - the organization's governance processes; - applicable national and European regulations. Organizations deploying AI in high-risk scenarios should complement SweetHive's technical safeguards with appropriate risk management, documentation, monitoring and governance procedures, as required by the AI Act. ## Built for responsible AI Rather than treating AI as an isolated chatbot with broad access to organizational knowledge, SweetHive integrates AI into a secure collaboration environment where every action is governed by the same visibility rules, permissions and organizational structure users already trust. The result is AI that is: - **secure by design** - **private by design** - **governed by design** - **human-controlled by design** - **ready for enterprise AI adoption** --- # Build an app Developers can build custom apps for SweetHive - a small data view embedded in a context, or a full product on its own URL. You register the app once, receive client credentials, and build against the **App SDK**. ## Two kinds of app | | **Embedded** | **External** | |---|---|---| | Where it runs | inside the SweetHive context UI (a sandboxed iframe) | its own URL / domain, launched from SweetHive | | Good for | data views, forms, dashboards scoped to a context | full products with their own UI | Both authenticate the same way: a **short-lived scoped token**, bounded server-side by the install's scope **and** the viewer's live visibility. Your app never sees more than the person using it can see, and access is revoked the instant they lose it. Most products combine both: a **hub app** (the External console at `hub.sweethive.com`) plus one or more **app widgets** - the Embedded view shown inside a context. In the app's own settings you pick which contexts of the hive display the widget, so the same app is both a place to run the workflow and a panel that lives inside the relevant contexts. ## Register and build 1. Open **Developer → Apps** from the user menu. 2. Choose **Register app**: name it, pick *Embedded* or *External*, set the URL, icon and capability. 3. Save the **client ID and secret** (shown once). 4. **Download the SDK dev guide (.md)** - the complete contract: the iframe handshake, auth, the scoped data API, testing and publishing. Drop it into your repo and build with your AI coding assistant. Also available here: [SWEETHIVE_APP_SDK.md](/downloads/SWEETHIVE_APP_SDK.md). 5. Set the app to **Active** so hive admins can install it from *Context → Apps → Add app*. ## How the standard works - **Embedded apps** run in a sandboxed iframe and receive a short-lived scoped token via a `postMessage` handshake - never a cookie, so it also works in the mobile apps. Your app must allow SweetHive to frame it (a `frame-ancestors` CSP that includes the mobile app origins - the SDK guide gives the exact header). - **External apps** open at their own URL with a signed launch; on mobile they open in the native in-app browser. - Every data call is bounded server-side by the install scope intersected with the viewer's live visibility - same law, same audit as any SweetHive actor. ## External apps and hubs An external app is a full product on its own URL. SweetHive shows a launch tile; on click the app opens with a **signed launch** and starts its own session - on mobile in the native in-app browser. External apps on an allowlisted origin can also sign users in directly with their SweetHive account (**SSO**): with a live SweetHive session there is no password prompt; otherwise the user signs in on the SweetHive login page and is bounced straight back into the app. Request the allowlisting when you register the app. ### Multi-hive hubs: one shell, many apps A product that manages several hives from one UI follows the **hub shell standard** - one reusable shell shaped by a manifest: - The **shell** provides, once for every app: SSO sign-in, the top-right hive selector, Team and Invitations management, light/dark theme and the collapsible sidebar. - The **manifest** (stored with the app registration) declares the brand and the left-panel entries. Each entry opens a view built into the shell or - the key part - **any embedded SweetHive app rendered in a frame, unchanged**: one build serves the context UI and the hub. - Switching hive re-scopes everything: the shell resolves the app's install in the selected hive and reloads the active view, so every screen follows the hive - including empty states for hives where the app isn't installed. The SDK guide has the full contract: the manifest schema, the view handshake and the pitfalls. ## Test and publish Register your app with a localhost URL, install it into a test context, and the handshake delivers a real scoped token against your data. When it's ready, set it **Active** - and disable it anytime; installs stop immediately. ## App settings An installed app can carry per-install **settings** - small configuration a hive admin sets (a linked resource, an integration key, a mode). They are stored with the install and delivered in the launch payload; the app reads them at startup and again when the admin changes them, no redeploy. Use this for *configuration*. Your app's **domain data** (its records) belongs in your own store, keyed by the install or its context - SweetHive gives identity, scope and people/groups; your app owns its data. ## Roles & permissions A **role** is a named set of your app's **features**, assigned to **groups** - never to individual people: members inherit it through their group. **Groups and people come from SweetHive**, listed for the context the app is installed in (your app reads them). **Roles are your app's data** - create them in your own store, then assign each to the right groups (search the install context's groups for large hives). Two steps in order: create the role (name + features), then assign it to groups. ## Connect apps to each other Apps don't call each other directly - they connect through the SweetHive **connectors** layer. One app **emits an event** (say, "a lead was captured") and a per-hive **connector** routes it to another app's **action** (say, "record marketing attribution"). Turning an integration on or off is a setting, not code in either app, so the two apps stay independent. - **Register** once what your app emits and what it accepts (its actions). - **Wire a connector** for a hive: source app + event to target app + action. An admin manages these from the Connectors page; enable, disable or remove them at any time. - **Delivery is best-effort**: if the other app is down, your app's own flow is never affected, and every delivery is logged so an admin can see what happened. An optional field mapping lets any event feed any action even when the field names differ, so new integrations are pure configuration. The SDK guide has the event/action contract and the exact endpoints. --- # MCP connector setup SweetHive exposes its Agent Client API as an **MCP server**. Any MCP-capable agent - Claude Desktop, Claude Code, Cowork, OpenClaw-class agents and others - connects with one **scoped access token** you issue from SweetHive. One server, one token model, every client. First, [create a token](/en/connect-an-agent/) in **My agents → Connect an agent** and download the config bundle (it contains your `endpoint` and `token`). ## What your agent gets | Tool | Does | |---|---| | `whoami` | the token's effective scope, capability and owner | | `contexts` | the granted hive/context tree | | `items` | recent items from a context and its subtree | | `search` | search messages, notes and files across granted contexts | | `post_message` | post into a context (*Read + post* tokens only; first post asks your confirmation) | | `chat_pull` / `chat_reply` | the [in-SweetHive chat](/en/chat-with-your-agent/) with you | ## Configure your client **Local connector (stdio)** - works today with Claude Desktop, Claude Code and any stdio-MCP client. Install the packaged SweetHive connector, then add: ```json { "mcpServers": { "sweethive": { "command": "node", "args": ["/absolute/path/to/sweethive-connector/dist/index.js"], "env": { "SWEETHIVE_ENDPOINT": "https://sweethive.com/server/web", "SWEETHIVE_TOKEN": "shv_..." } } } } ``` **Remote (streamable HTTP)** - where the hosted MCP endpoint is enabled, point your client at it with the token as a Bearer credential: ```json { "mcpServers": { "sweethive": { "url": "https://sweethive.com/mcp", "headers": { "Authorization": "Bearer shv_..." } } } } ``` Your agent can now answer things like *“what changed in Project A this week?”* or *“draft a status update for the DevGroup.”* ## Notes - **Capability** (Read / Read + draft / Read + post) is fixed on the token; read-only is the default. - **Revocation and group changes take effect immediately** - there is no cached scope. A leaked config exposes a bounded, killable scope, never your account credentials. - Content flowing in from an external agent is treated as untrusted: it cannot carry privileged mentions or invoke internal SweetHive agents, and it is rate-limited per token.