# What is Buda (/docs) **Buda is a cloud-native AI agent workspace.** Recruit a team of AI agents, give them work, and watch them execute live in their own cloud computers — no Mac mini, no local setup. You direct; they ship. The Buda dashboard Agents as a company [#agents-as-a-company] For founders, solo builders, and small teams, the bottleneck isn't ideas — it's hands. Every task waits on one person, and work disappears between runs. Buda turns that around by letting you run agents the way a CEO runs a company: > **Humanity leads · Buda manages · Claws execute** * **You are the CEO** — you set direction and review the work. * **Buda is the manager** — the Organizer coordinates your agents and keeps work moving. * **Claws are the workforce** — agents that actually execute, in parallel, in the cloud. Each agent runs in an isolated, long-running **cloud computer** with a persistent Drive and memory. You can watch every step across files, browser, terminal, and Git — and turn anything repeatable into a reusable Skill or scheduled Automation. What you can do with Buda [#what-you-can-do-with-buda] New here? Start at the top [#new-here-start-at-the-top] Buda is independently developed and shares a multi-agent philosophy with local agent tools — but runs entirely in the cloud, so there's nothing to install. # Delete your account (/docs/account/delete-account) Closing your account should be deliberate and clear. This page explains exactly what deletion does, what to wrap up first, and what happens to your data — so there are no surprises. Deletion is **permanent**. The moment you confirm, you're signed out everywhere and can no longer access your account. Before you delete [#before-you-delete] Account deletion closes **your user account** — it does not, on its own, refund or cancel a Space's subscription. Before you go: * **Wind down any paid plans.** If you own a Space with an active subscription, cancel it from **Space Settings → Billing** so it isn't renewed. * **Hand off shared work.** If teammates rely on Spaces, agents, or files you manage, transfer ownership or make sure someone else has access. * **Save anything you need.** Export or download work you want to keep — you won't be able to retrieve it afterward. The deletion flow [#the-deletion-flow] Open account settings [#open-account-settings] Go to **Settings** from your **avatar** in the bottom-left corner and find the account deletion option. Confirm by typing your email [#confirm-by-typing-your-email] To guard against accidental deletion, you must **re-type your account email exactly**. If it doesn't match, the deletion is rejected. Confirm [#confirm] Once confirmed, your account is closed immediately and **all your sessions are revoked** — you're signed out on every device. Data retention [#data-retention] When you delete your account, Buda first **deactivates** it — the account is instantly and permanently inaccessible. The underlying data is then **fully removed** during routine cleanup that runs afterward, rather than at the exact moment you click confirm. Note that content living at the **Space** level (files, Space Drive, agent work) belongs to the Space, not to your personal account. Deleting your account removes your access; handing off or deleting that content is a separate step you should take beforehand. Reactivation [#reactivation] Because deletion is permanent and the account is locked out immediately, there's **no self-serve way to reactivate** it. If you deleted by mistake or change your mind shortly after, contact support as soon as possible — recovery may not be possible once cleanup has run. Related [#related] # Notifications (/docs/account/notifications) When something needs your attention — an invite to act on, an approval to confirm — Buda surfaces it in one place so nothing slips through. The in-app inbox keeps account and workspace events together, each linking straight to where you need to go. Where notifications appear [#where-notifications-appear] Notifications show up in your **in-app inbox** (the notification bell). Each one has: * A **title** and a short **message**. * A **read / unread** state — unread items are highlighted. * An optional **link** that takes you straight to the relevant page (for example, a pending invitation). Mark as read and dismiss [#mark-as-read-and-dismiss] From the inbox you can: * **Mark a single notification as read** — opening or clicking it clears its unread state. * **Mark all as read** — clear the unread badge in one action. * **Delete a notification** — remove it from the list once you've dealt with it. Notifications are tied to your **user account**, so you see the same inbox no matter which Space you're working in. What triggers them [#what-triggers-them] In-app notifications are created for account and team events, such as: * A **team invitation** you've been sent, or one you sent being **accepted**. * **Waitlist approval** with your invite code. * **Invite-code activation** confirming you're in. In-app vs email [#in-app-vs-email] This page covers **in-app** notifications. Email alerts are separate and configurable — turn categories like workspace activity, mentions, system updates, and billing on or off under [Profile and preferences](/en/docs/account/profile-and-preferences#notification-preferences). Related [#related] # Profile and preferences (/docs/account/profile-and-preferences) Make Buda feel like yours. A few minutes in settings — the right theme, your language, and which emails you actually want — keeps the interface out of your way so you can focus on directing your agents. Open **Settings** from your **avatar** in the bottom-left corner. Profile basics [#profile-basics] Under **Settings → Profile** you can: * **Update your name** — how you appear to teammates. * **Set or change your avatar** — upload an image, or remove it to fall back to the default. Your profile is tied to your **user account**, so it's the same across every Space you belong to. Theme and language [#theme-and-language] * **Theme** — choose **System** (follow your device), **Light**, or **Dark**. * **Language** — choose **Auto** (follow your browser/device) or pick a specific supported language. The interface updates immediately. Theme and language are personal account settings — changing them only affects what *you* see, not your teammates. Notification preferences [#notification-preferences] Buda can email you about account and workspace activity. Under **Settings**, toggle email notifications on or off overall, and fine-tune which kinds you receive: * **Workspace activity** — updates from Spaces you belong to. * **Mentions** — when someone mentions you. * **System updates** — important product and account notices. * **Billing** — payment, plan, and credit-related emails. In-app notifications (the bell in the app) are covered separately — see [Notifications](/en/docs/account/notifications). Keyboard shortcuts [#keyboard-shortcuts] Move faster without leaving the keyboard. Buda's built-in shortcuts (modifier is **⌘** on macOS, **Ctrl** on Windows/Linux): | Action | Shortcut | | --------------------- | ---------------------------------------------------------- | | Quick search | **⌘/Ctrl + G** | | New chat | **⌘ + ⌃ + N** (macOS) · **Ctrl + Alt + N** (Windows/Linux) | | Switch to session 1–9 | **⌘/Ctrl + 1** … **⌘/Ctrl + 9** | Related [#related] # What are credits (/docs/billing/credits) Credits are how Buda meters AI work, so you always know what's left before an agent stops mid-task. Understanding the three pools — and which models burn more — lets you run more work for less. What are credits? [#what-are-credits] Credits are Buda's unit for measuring AI usage. Every time your Agent runs a task, it consumes a certain number of credits. The more complex the task or the longer it runs, the more credits it uses. Credits are not currency and not tokens — they're a composite unit that covers all the resources needed to run an Agent. What Do Credits Cover? [#what-do-credits-cover] Each time an Agent works, credits are consumed across two areas: * **LLM Tokens**: The cost of calling AI models (GPT, Claude, Gemini, etc.) for thinking, planning, and generating responses * **Third-party APIs**: External services called by the Agent (e.g., search, data feeds) Three-Pool Credit System [#three-pool-credit-system] Each workspace has three separate credit pools, consumed in this order: 1. **Daily Credits** — Automatically reset at UTC 00:00 every day 2. **Monthly Credits** — Automatically reset each subscription cycle 3. **Balance Credits** — Manually topped up, may have an expiry date for promotional credits, otherwise do not expire When all three pools are exhausted, AI features pause until credits reset or you top up. Do Credits Expire? [#do-credits-expire] * **Daily Credits**: Reset every day; unused credits don't carry over * **Monthly Credits**: Reset each subscription cycle; unused credits don't carry over * **Balance Credits**: Generally do not expire — top up once and use whenever you need (promotional credits may have an expiry date) What Doesn't Consume Credits? [#what-doesnt-consume-credits] * Browsing files or viewing conversation history * Storing and accessing completed tasks * Managing team members or changing settings Credits are only consumed **when an Agent is actively executing a task**. Models & Credit Multipliers [#models--credit-multipliers] Different AI models have different capabilities and costs. Buda uses a **Multiplier** system to show how much each model costs relative to the baseline: * **1x** = baseline cost * **> 1x** = more powerful, uses more credits (e.g. 3x means \~3× the credits) * **\< 1x** = lighter and cheaper to run Example: the same task on a 3x model costs about 3× more credits than on a 1x model. > Multipliers are for relative comparison only. Actual usage also depends on input length and output size. You can switch models in Agent settings. Choosing a lighter model for simple tasks is the most direct way to save credits. 👉 **[View full AI model credit comparison →](/pricing#models)** How to save credits [#how-to-save-credits] * **Be specific about your task**: Vague instructions make the Agent iterate more before understanding what you want. "Sort this Excel by revenue descending and export as PDF" uses fewer credits than "process this file". * **Batch related tasks**: Combine several related requests into one instead of sending them separately. * **Review intermediate results**: For multi-step tasks, check each stage before continuing to avoid wasting credits on a wrong direction. * **Choose the right model**: Use lighter models for simple tasks, reserve powerful models for complex ones. Adjust the default model in Agent settings. How to Monitor Usage? [#how-to-monitor-usage] In the billing page of your dashboard, you can see: * **Current balance**: Real-time balance across all three credit pools * **Usage history**: How many credits each task consumed * **Spending insights**: Which task types consume the most credits See [Track usage](/en/docs/billing/usage) for a full walkthrough of the usage panel. How to add more credits [#how-to-add-more-credits] * **Upgrade your plan**: Plus and Pro plans include more monthly credits automatically * **Purchase Balance Credits**: Top up anytime from the billing page — they generally do not expire (promotional credits may have an expiry date) * **Redeem codes**: Codes from courses, events, or partners are added directly to your Balance Credits What Happens When Credits Run Out? [#what-happens-when-credits-run-out] When all three pools are exhausted, Agents pause until: * Daily Credits reset at the next UTC 00:00 * Monthly Credits reset at the next subscription cycle * You top up Balance Credits from the billing page (takes effect immediately) FAQ [#faq] **Q: Are credits the same as tokens?** No. Tokens are a model-level unit. Credits are Buda's composite unit that includes model calls, compute resources, and more. **Q: Do all Agents in a workspace share credits?** Yes. All Agents in a workspace share the same credit pools — credits are not tracked per Agent. **Q: How many credits does the Free plan include?** The Free plan includes 300 Daily Credits per day, with no Monthly Credits. It's designed for light exploration. **Q: Where can I check my current credit balance?** Your credit balance is visible at the top of the dashboard and in the billing settings page. For the conceptual model behind Spaces, pools, and per-Space billing, see [Credits & billing model](/en/docs/concepts/credits-and-billing-model). Related [#related] # Plans & pricing (/docs/billing) Pick a plan that matches how many agents you run, then let the whole team draw from one shared pool. Buda bills **per Space** — not per person — so you pay for a workspace's capacity, and every agent and teammate inside it shares the same credits, storage, and limits. Overview [#overview] Buda uses a **three-pool credit system** to manage AI usage per Space: 1. **Daily Credits** — Reset every day at UTC 00:00 2. **Monthly Credits** — Reset each subscription billing cycle 3. **Balance Credits** — Purchased or recharged — generally do not expire Credits are consumed in order: Daily → Monthly → Balance. When all pools are exhausted, AI features are paused until credits reset or you recharge. Billing Unit: Space, not User [#billing-unit-space-not-user] **Subscriptions are billed per Space** — not per individual user account. A Space is your company's workspace: it holds all your Agents, files, team members, and a shared credit balance. One person can belong to multiple Spaces (e.g. your own startup and a client's workspace), and each Space is billed independently. Plans [#plans] | | Free | Plus | Pro | Enterprise | | ------------------------ | --------------------------------------- | --------------------------- | ---------------------------- | ---------- | | Price (monthly) | $0 | $20 / agent | $100 / agent | Custom | | Price (annual) | — | $17 / agent / mo | $84 / agent / mo | Custom | | Daily Credits | 300 | 300 | 300 | 300 | | Monthly Credits | — | +4,000 / agent → Space pool | +20,000 / agent → Space pool | Unlimited | | Agent SSD Drive | 500 MB / agent | 2 GB / agent | 10 GB / agent | Custom | | Space Drive | 1 GB | 50 GB | 200 GB | Unlimited | | Browser / Terminal / Git | ✗ | ✓ | ✓ | ✓ | | Automations | Up to 5, min. 120 min interval, no cron | ✓ | ✓ | ✓ | How monthly credits accumulate [#how-monthly-credits-accumulate] Each Agent you purchase **adds** its monthly credit allowance to the Space's shared pool — credits are not capped per Agent. **Example:** A Pro Space with 10 Agents gets 10 × 20,000 = **200,000 credits/month** shared across all Agents in that Space. Two Types of Storage [#two-types-of-storage] | | Agent SSD Drive (`/agent`) | Space Drive (`/space`) | | ----------- | ---------------------------------------- | ------------------------------------------------- | | Scope | Private to each Agent | Shared across all Agents in the Space | | Performance | High-performance SSD | Standard storage | | Best for | Active tasks, code execution, temp files | Knowledge bases, shared assets, cross-Agent files | | Persists? | Yes, across sessions | Yes | See [Space Drive](/en/docs/billing/space-drive) for details. How Credits Are Consumed [#how-credits-are-consumed] Each AI message costs credits based on the model used. More capable models consume more credits per message, while lighter models are more economical. You can check your credit usage in **Space Settings → Credit Usage**. The minimum charge is 1 credit per message. User Rewards [#user-rewards] **User Rewards** are personal credits tied to your **User Account** (not any specific Space). You can earn them through: * Referral bonuses (invite friends) * Onboarding completion * Promotions and early adopter rewards View your reward balance at **Settings → Rewards**. Recharging Space Balance [#recharging-space-balance] You can convert your personal Reward balance into Space Balance Credits: 1. Go to **Settings → Rewards** 2. Click **Recharge** 3. Select the target Space 4. Enter the amount 5. Confirm — credits appear in that Space's Balance Credits pool immediately Balance Credits never expire and are shared across all Agents in the Space. What Happens When Credits Run Out [#what-happens-when-credits-run-out] When all three pools are exhausted: * A **dialog** appears in chat prompting you to upgrade or recharge * The **Billing** page shows a red "Quota Exceeded" warning * AI features are paused until credits reset (daily/monthly) or you recharge Viewing Usage [#viewing-usage] * **Space Settings → Billing** — See all credit pools, storage, and agents * **Space Settings → Credit Usage** — Transaction history of every AI message Upgrading Your Plan [#upgrading-your-plan] Go to **Space Settings → Billing** and scroll to Pricing Cards. Click **Upgrade** to start a subscription. Your monthly credits increase immediately. FAQ [#faq] **What's the difference between a User Account and a Space?** Your User Account is your personal login identity. A Space is the billing and organizational unit — it holds Agents, files, members, and a shared credit balance. You can belong to multiple Spaces with one User Account. **Are credits per Agent or per Space?** Credits are pooled at the Space level. Each Agent you purchase adds its monthly allowance to the Space's shared pool. No Agent has its own credit cap. **What's the difference between Monthly Credits and Balance Credits?** Monthly Credits are included in your plan and reset each billing cycle — unused credits don't carry over. Balance Credits are added via top-up purchases or Reward recharges; they never expire and are never cleared on reset. **How many members can I invite?** Each Agent includes one human member slot. For example, purchasing 5 Agents lets you invite 5 team members. **Can I add more credits without upgrading?** Yes. Earn rewards by inviting friends, then recharge them to your Space as Balance Credits. You can also purchase additional credit top-ups directly. **Do unused daily credits roll over?** No. Daily credits reset at UTC midnight each day. Monthly credits reset at the start of each billing cycle. Balance credits never expire. **What models are available?** Buda supports 12+ AI models including Claude, GPT, Gemini, DeepSeek, and more. All models are available on all plans — they just consume credits at different rates. For the full conceptual breakdown of how Spaces, credits, and billing fit together, see [Credits & billing model](/en/docs/concepts/credits-and-billing-model). Related [#related] # Payment methods (/docs/billing/payment-methods) Wherever you are, there's a way to pay. Buda accepts international cards plus the wallets people actually use day to day, so checkout takes seconds and your agents keep running. Supported methods [#supported-methods] At checkout you can pay with: | Method | Best for | | ------------------------------------------ | ----------------------------------------------------------------- | | **Credit / debit card** (Visa, Mastercard) | The default — fastest for most regions | | **PayPal** | Anyone who prefers paying from a PayPal balance or linked account | | **Alipay** | Users in mainland China | | **WeChat Pay** | Users in mainland China | Card is shown first as the primary option; PayPal, Alipay, and WeChat Pay appear under **More payment methods**. The methods available can vary slightly by the product you're buying (a subscription, a credit top-up, or a marketplace item). How to pay [#how-to-pay] 1. Open **Space Settings → Billing** and choose a plan or top-up. 2. On the checkout screen, pick your **payment method**. 3. Complete payment — card and PayPal redirect to a secure flow; Alipay and WeChat Pay show a QR code to scan. 4. Once payment confirms, your plan or credits update on the Space immediately. Subscriptions are billed **per Space**. The person who checks out pays, but the plan and credits belong to the Space — not to their personal account. See [Credits & billing model](/en/docs/concepts/credits-and-billing-model). Invoices and receipts [#invoices-and-receipts] Buda processes payments through a **merchant of record**, which issues your receipt. After a successful payment: * A **receipt / invoice** is emailed to the address on the payment. * The transaction also appears in your Space's billing history. If you need a receipt resent or a tax detail corrected, contact support with your Space name and the payment date. Managing your subscription [#managing-your-subscription] To change or cancel a plan, go to **Space Settings → Billing**: * **Upgrade** — takes effect immediately; new monthly credits are added right away. * **Downgrade or cancel** — your current plan stays active until the end of the paid period, then the Space reverts to Free. A self-serve billing portal for editing saved cards isn't available yet. For card or charge changes that you can't make from Space Settings, reach out to support. Related [#related] # Grant programs (/docs/billing/programs) If you're a student, an early-stage startup, a nonprofit, or an open-source maintainer, you can run a team of agents on Buda without paying. Each grant unlocks **Plus** for a Space — plus a set of agent slots — for 90 days, so you can build for real before you commit a budget. Available programs [#available-programs] | Program | Plan | Agent slots | Duration | | --------------------- | ---- | ----------- | -------- | | **Student** | Plus | 2 | 90 days | | **Startup** | Plus | 5 | 90 days | | **Nonprofit** | Plus | 3 | 90 days | | **Open source (OSS)** | Plus | 3 | 90 days | A grant applies to **one Space** (your first/default Space) and raises both its plan and its effective agent quota for the grant period. Eligibility [#eligibility] * **Student** — an active student with a school email. Addresses on academic domains (such as `.edu` or `.ac.*`) are approved automatically; others are reviewed manually. * **Startup** — an early-stage company. Applications go through a quick automated screen plus a manual review. * **Nonprofit** — a registered nonprofit or mission-driven organization. Reviewed manually after an automated screen. * **Open source (OSS)** — a maintainer or contributor to a meaningful open-source project. Each program is self-serve. Approvals for non-academic applications are handled by the Buda team, so allow some time for review. Apply [#apply] Open the application form [#open-the-application-form] Go to the program's survey page: * Student — `/survey/program_student` * Startup — `/survey/program_startup` * Nonprofit — `/survey/program_nonprofit` * Open source — `/survey/program_oss` Fill in your details [#fill-in-your-details] Answer the form questions and submit. Use your **school email** for the student program so it can be verified automatically. Get approved [#get-approved] Eligible student applications with an academic email are approved instantly. Other applications are reviewed by the Buda team; you'll be notified of the decision. Start building [#start-building] Once approved, your Space is upgraded to **Plus** with its agent slots, ready to use immediately. Grant duration and expiry [#grant-duration-and-expiry] * Each grant lasts **90 days**. * When it expires, the Space automatically **reverts to Free**; its plan limits and agent quota return to the free tier. * Any work, files, and Space Drive contents stay in place — only the plan changes. You can subscribe to a paid plan at any time to keep the higher limits. Related [#related] # Redeem a reward code (/docs/billing/redeem) Got a code from a course, event, or partner? Redeeming it drops **reward balance** into your account, which you then recharge into any Space as AI Credits — so your agents can keep working without a card on file. What is a reward code? [#what-is-a-reward-code] A reward code is an exclusive code issued by Buda. After redemption you receive **reward balance** that can be converted into AI Credits to power your agents. Reward balance belongs to your **user account** (your personal identity), not to a Space. When you recharge, you choose which Space to top up — the credits then enter that Space's shared pool and become available to every agent in it. See [Credits & billing model](/en/docs/concepts/credits-and-billing-model) for how user-level rewards differ from per-Space subscriptions. Reward codes are distributed through early adopter perks, promotional campaigns, and partner programs. How to redeem [#how-to-redeem] Open Rewards [#open-rewards] 1. Sign in to [buda.im](https://buda.im). 2. Click your **avatar** in the bottom-left corner. 3. Select **Settings**, then switch to the **Rewards** tab. 4. Click **Redeem code**. Enter your code [#enter-your-code] On the `/redeem` page: 1. Enter your code (format: `BUDA-XXXX-XXXX`). 2. Select the **Space** to apply it to. 3. Click **Redeem**. A confirmation animation appears and your reward balance is credited instantly. Recharge into AI Credits [#recharge-into-ai-credits] Reward balance must be converted to AI Credits before agents can use it: 1. Go back to **Settings → Rewards**. 2. Click **Recharge** on the **Recharge AI Credits** card. 3. Enter the amount to convert. 4. Confirm — credits appear in that Space's balance pool immediately. Check your balance [#check-your-balance] Open **Settings → Billing** to see your updated **AI Credits balance**. FAQ [#faq] **Can a reward code be used more than once?** No. Each code can only be redeemed once. **Does reward balance expire?** Reward balance and recharged balance credits generally do not expire. Some promotional grants carry an expiry date, which is shown at redemption time. **Can I apply a code to multiple Spaces?** No. You select one Space at redemption time. **What's the conversion rate?** $1 of reward balance = 100 AI Credits. **Is reward balance tied to my account or my Space?** It's held at the **user account** level. When you recharge, you pick a target Space — the credits are deposited into that Space's shared pool. This is different from a subscription, which is billed directly to the Space. Related [#related] # Referral program (/docs/billing/referral) Tell a friend, get rewarded. When someone signs up with your referral code and verifies their email, **both of you** earn reward balance you can recharge into any Space — real credits for real AI work, just for spreading the word. How rewards work [#how-rewards-work] * **You (the referrer)** earn **$5.00** of reward balance. * **Your friend (the new user)** earns **$2.00** of reward balance. Rewards are granted as **balance credits** held at the **user account** level. Recharge them into a Space to turn them into AI Credits — see [Redeem a reward code](/en/docs/billing/redeem) for the recharge flow, which works the same way. Referral rewards **expire 30 days** after they're granted, so recharge them into a Space and put them to work soon after they land. Get your referral code [#get-your-referral-code] Open your referral details [#open-your-referral-details] Go to **Settings → Rewards** (or the referral section of your account). Your personal referral code is shown there, along with a shareable link. Share it [#share-it] Send your code or link to a friend. They enter the code when they sign up for Buda. They verify their email [#they-verify-their-email] The reward is granted only **after** your friend verifies their email address. Until then, the referral is recorded but not yet paid out. Eligibility and expiry [#eligibility-and-expiry] A referral pays out only when **all** of these are true: * The new user signed up with a **valid referral code**. * They've **verified their email**. * It isn't a **self-referral** — you can't refer your own account. * That user hasn't already been referred or rewarded before. Each granted reward **expires 30 days** after it's issued. Track earnings [#track-earnings] In **Settings → Rewards** you can see: * Your **referral code**. * How many people you've **successfully referred**. * Your **total earned** reward balance. From the same page, recharge your balance into a Space whenever you're ready to use it. Related [#related] # Space Drive (/docs/billing/space-drive) Space Drive is your Space's **shared memory** — a `/space` directory that every Agent in your Space can read and write. Think of it as a shared file cabinet for your whole team, accessible to all Agents simultaneously. An agent session working with files in the cloud computer Space Drive vs Agent SSD Drive [#space-drive-vs-agent-ssd-drive] Buda provides two types of storage for different purposes: | | Agent SSD Drive (`/agent`) | Space Drive (`/space`) | | ------------------------- | ---------------------------------------- | ------------------------------------------------- | | Scope | Private to one Agent | Shared across all Agents in the Space | | Performance | High-performance SSD | Standard storage | | Best for | Active tasks, code execution, temp files | Knowledge bases, shared assets, cross-Agent files | | Persists across sessions? | Yes | Yes | | Visible to other Agents? | No | Yes | Storage Limits by Plan [#storage-limits-by-plan] | Plan | Space Drive | | ---------- | ----------- | | Free | 1 GB | | Plus | 50 GB | | Pro | 200 GB | | Enterprise | Unlimited | What to Store in Space Drive [#what-to-store-in-space-drive] Space Drive is ideal for content that multiple Agents need to access: * **Company knowledge base** — SOPs, policies, reference documents * **Shared assets** — templates, brand files, datasets * **Cross-Agent handoffs** — files one Agent produces that another Agent consumes * **Project files** — long-running work that outlasts any single session What to Store in Agent SSD Drive [#what-to-store-in-agent-ssd-drive] Keep Agent-specific content in `/agent`: * Active working files for a task in progress * Installed packages and dependencies * Temporary outputs and cache * Configuration files specific to that Agent Accessing Space Drive [#accessing-space-drive] Inside an Agent's Terminal or code execution environment, Space Drive is mounted at `/space`. You can read and write files there just like any other directory: ```bash # List files in Space Drive ls /space # Write a file that other Agents can read echo "shared data" > /space/shared-output.txt # Read a file another Agent wrote cat /space/report-from-agent-2.md ``` Use Cases [#use-cases] **Multi-Agent pipeline**: Agent A researches and writes findings to `/space/research.md`. Agent B reads that file and generates a report. **Shared knowledge base**: Upload your company SOPs to Space Drive once. All Agents can reference them without duplicating files. **Long-running projects**: Store project state in `/space` so any Agent can pick up where another left off. Related [#related] * [Plans & pricing](/en/docs/billing) — Space Drive storage limits by plan * [Credits & billing model](/en/docs/concepts/credits-and-billing-model) — How Spaces, storage, and credits fit together * [Track usage](/en/docs/billing/usage) — Monitor storage and credit quotas # Track usage (/docs/billing/usage) Nothing kills momentum like an agent stalling mid-task because credits ran out. The usage panel shows exactly how much of each pool you've burned, what's left, and when it resets — so you can top up or switch models *before* work stops. The usage panel [#the-usage-panel] Open **Space Settings → Billing** (or **Credit Usage**) to see your Space's live status: * **Each credit pool** — daily, monthly, and balance — with how much is used, the limit, and a progress bar. * **When each pool resets** — daily pools reset at UTC 00:00; monthly pools reset at the start of each billing cycle; balance credits don't reset. * **Storage** — Agent SSD Drive and Space Drive usage against their limits. * **A warning state** as a pool nears its limit, and an **exhausted** state when it's empty. The current balance also appears at the top of your dashboard for an at-a-glance check. Per-pool consumption [#per-pool-consumption] Credits are spent from your three pools **in order**: 1. **Daily credits** first. 2. **Monthly credits** next (paid plans). 3. **Balance credits** last. This means promotional or daily allowances get used up before your purchased balance — so balance credits stretch as far as possible. When all three are empty, AI features pause until a pool resets or you top up. All agents in a Space draw from the **same** pools — usage is tracked per Space, not per agent. Model cost multipliers [#model-cost-multipliers] Each AI message costs credits based on the model it runs on. Buda uses a **multiplier** to show relative cost: * **1×** — baseline cost. * **> 1×** — more capable, costs proportionally more (e.g. a 3× model costs about three times as much per message). * **\< 1×** — lighter and cheaper. The minimum charge is **1 credit per message**. Actual cost also depends on input length and output size, so multipliers are for comparison, not an exact price. Switching to a lighter model for simple tasks is the most direct way to save credits. You can change the model in agent settings. See the [full model comparison](/pricing#models). Quota limits [#quota-limits] Beyond credits, each plan caps a few other resources per Space: * **Storage** — Agent SSD Drive and [Space Drive](/en/docs/billing/space-drive). * **Seats and agents** — how many teammates and agents the Space allows. * **Automations** — number of scheduled tasks and the minimum interval between runs. When a quota is reached, the related feature is blocked until you free up space, remove items, or upgrade. Upgrade anytime from **Space Settings → Billing**; increases take effect immediately. Related [#related] # Connect DingTalk (/docs/channels/dingtalk) Bring your agent into DingTalk so colleagues can chat with it in DMs and groups. Buda connects over DingTalk's **Stream Mode** — a persistent outbound WebSocket — so there's no public URL to host. A DingTalk message answered by a Buda agent Connect the bot [#connect-the-bot] Buda offers two ways to connect: scan a QR code and let DingTalk create the app for you, or enter credentials from an app you've already created. Open Add Channel [#open-add-channel] In Buda, open **Settings → Channels**, click **Add Channel**, and select **DingTalk**. Scan to connect (recommended) [#scan-to-connect-recommended] On the **Scan to connect** tab, click **Start scan**. Buda shows a QR code — open DingTalk, scan it, and confirm the authorization in the app. DingTalk registers an app in your organization and returns its credentials directly to Buda, so you never have to open the DingTalk Developer Portal yourself. Or enter credentials manually [#or-enter-credentials-manually] Switch to the **Enter manually** tab if you already have an app. Create (or reuse) an internal app in the [DingTalk Developer Portal](https://open.dingtalk.com/document/development/create-dingtalk-intelligent-agent-application) with bot/robot capability and Stream Mode enabled, then copy its: * **Client ID (AppKey)** * **Client Secret (AppSecret)** Paste both into Buda, optionally set a label and **target agent**, then click **Connect**. Test it [#test-it] Find the bot in DingTalk and send it a direct message, e.g. `Hi`. In a group, **@mention** the bot to get a reply. Use it in a group [#use-it-in-a-group] Add the bot to a DingTalk group and **@mention** it to trigger a reply — group messages that don't mention the bot are ignored. Direct messages don't need a mention. Only text messages are handled today — DingTalk messages of other types (images, files, cards, etc.) are ignored. Troubleshooting [#troubleshooting] | Symptom | Fix | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | Bot not responding | Confirm the channel shows **Active**; re-check the Client ID / Client Secret if you connected manually | | No reply in a group | You must @mention the bot in group chats | | QR code expired | Start the scan again from **Add Channel** | | Credentials compromised | Reset the AppSecret in the DingTalk Developer Portal, then update it in Buda's channel settings | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [DingTalk Developer Portal](https://open.dingtalk.com/document/development/create-dingtalk-intelligent-agent-application) # Connect Discord (/docs/channels/discord) Bring your agent into a Discord server for community support, developer Q\&A, or async teamwork. Buda connects over Discord's native **Gateway (WebSocket)** — provide a bot token and Buda holds a persistent connection in the background for real-time, streaming replies. **No webhook URL or public endpoint needed.** A Discord message answered by a Buda agent Connect the bot [#connect-the-bot] Create an application [#create-an-application] Open the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, name it (e.g. `Buda Assistant`), accept the terms, and click **Create**. Get the bot token and enable Message Content Intent [#get-the-bot-token-and-enable-message-content-intent] Go to the **Bot** tab. Under **Token**, click **Reset Token** and copy the value — you'll paste it into Buda. Scroll to **Privileged Gateway Intents** and turn on **Message Content Intent**, then **Save Changes**. Without it, the bot can't read message text. Invite the bot to your server [#invite-the-bot-to-your-server] Go to **OAuth2 → URL Generator**. Under **Scopes** check `bot`, then under **Bot Permissions** check at least: `Send Messages`, `Read Message History`, `Embed Links`, `Attach Files`, `Add Reactions`, `View Channels`. Copy the generated URL, open it, select your server, and **Authorize**. Configure the channel in Buda [#configure-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **Discord**. Paste the **bot token**, optionally set a label and **target agent**, then save. Buda connects to Discord over WebSocket immediately. Start chatting [#start-chatting] **@mention** the bot in any channel, or send it a direct message. Buda processes the message and replies with streaming text. Troubleshooting [#troubleshooting] | Symptom | Fix | | ------------------------------------ | ----------------------------------------------------------------------- | | Bot reads nothing / ignores messages | **Message Content Intent** is off — enable it in the Bot tab and save | | Bot can't post | Re-check the OAuth2 scopes and bot permissions, then re-invite | | Token compromised | Reset the token in the Bot tab and update it in Buda's channel settings | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Connect Slack](/en/docs/channels/slack) — similar token-based, webhook-free setup # Connect Feishu / Lark (/docs/channels/feishu) Drop your agent into Feishu (Lark) for DMs and group chats. Buda connects over a **persistent WebSocket** — provide your App ID and App Secret and Buda holds the connection in the background. **No public webhook URL or tunneling required.** Lark (international) tenants: use [open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in your config. *** Step 1: Create a Feishu App [#step-1-create-a-feishu-app] 1.1 Open Feishu Open Platform [#11-open-feishu-open-platform] Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in. 1.2 Create an enterprise app [#12-create-an-enterprise-app] 1. Click **Create enterprise app** 2. Fill in the app name, description, and icon 3. Click **Create** Create enterprise app 1.3 Copy credentials [#13-copy-credentials] From **Credentials & Basic Info**, copy: ``` App ID: cli_xxxxxxxxxxxx App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` > App Secret is hidden by default — click "View" to reveal it. Keep it private. Get credentials 1.4 Configure permissions [#14-configure-permissions] In **Permissions**, click **Batch import** and paste: ```json { "scopes": { "tenant": [ "aily:file:read", "aily:file:write", "application:application.app_message_stats.overview:readonly", "application:application:self_manage", "application:bot.menu:write", "cardkit:card:read", "cardkit:card:write", "contact:user.employee_id:readonly", "contact:contact.base:readonly", "corehr:file:download", "event:ip_list", "im:chat.access_event.bot_p2p_chat:read", "im:chat.members:bot_access", "im:message", "im:message.group_at_msg:readonly", "im:message.p2p_msg:readonly", "im:message:readonly", "im:message:send_as_bot", "im:resource" ], "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"] } } ``` Configure permissions 1.5 Publish the app (first time) [#15-publish-the-app-first-time] **You must publish before enabling event subscriptions.** 1. Go to **Version Management & Release** → **Create Version** 2. Set version to `1.0.0`, click **Save** → **Submit for release** 3. Wait for approval (enterprise apps usually auto-approve) *** Step 2: Configure the channel in Buda [#step-2-configure-the-channel-in-buda] Open Buda's Channel settings, click **Add Channel**, and select **Lark** from the provider dropdown — this is the label Buda uses in the UI for the Feishu/Lark channel. Enter your App ID and App Secret, and save. Buda immediately establishes a WebSocket long connection to Feishu in the background. Complete this step before configuring event subscriptions — Feishu needs to detect the active connection first. *** Step 3: Enable event subscription [#step-3-enable-event-subscription] 1. Go to **Event Subscription** → **Event Configuration** 2. Enable **Use long connection to receive events** 3. Click **Add Event** and add `im.message.receive_v1` 4. Click **Save** Configure event subscription > ⚠️ If the long connection toggle is grayed out, the app hasn't been published yet. Complete step 1.5 first. *** Step 4: Publish a new version [#step-4-publish-a-new-version] After adding events, publish a new version for changes to take effect: 1. **Version Management & Release** → **Create Version**, increment the version (e.g. `1.0.1`) 2. Click **Save** → **Submit for release** *** Step 5: Test [#step-5-test] 1. Open Feishu and find your bot 2. Send a message, e.g. `Hello` 3. The bot replies — you're all set 🎉 *** Troubleshooting [#troubleshooting] Bot does not respond [#bot-does-not-respond] | Possible cause | Solution | | --------------------- | ------------------------------------------- | | Event not added | Check that `im.message.receive_v1` is added | | Missing permissions | Review step 1.4 | | Wrong credentials | Verify App ID and App Secret in Buda | | Version not published | Publish a new version after adding events | Long connection cannot be enabled [#long-connection-cannot-be-enabled] The app hasn't been published. Complete step 1.5 and wait 1–2 minutes before retrying. App Secret leaked [#app-secret-leaked] 1. Reset the App Secret in Feishu Open Platform 2. Update the App Secret in Buda 3. Restart the gateway *** Supported message types [#supported-message-types] Receive [#receive] * ✅ Text, rich text * ✅ Images, files, audio, video * ✅ Stickers Send [#send] * ✅ Text, images, files, audio, video * ✅ Interactive cards (streaming output) *** Configuration reference [#configuration-reference] Buda only asks for two fields when you add the channel — there's no other config to manage: | Field | Description | | ---------- | -------------------------------------------------------------------- | | App ID | Copied from **Credentials & Basic Info** on the Feishu Open Platform | | App Secret | Copied from the same page (click "View" to reveal it) | *** Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Connect WeCom](/en/docs/channels/wecom) — another enterprise messaging channel # Channels Overview (/docs/channels) Your agent is most useful where people already are — a WhatsApp thread, a Slack channel, a Feishu group, your own website. A **channel** connects one messaging surface to one Buda agent: it receives inbound messages, routes each conversation to the right chat session, and streams the agent's reply back. You set it up once; the connection stays alive in the background. An agent answering live in a chat session How a channel works [#how-a-channel-works] Every channel does the same four things, regardless of provider: * **Receives** inbound user messages from the connected platform. * **Routes** each user or group conversation to its own [chat session](/en/docs/concepts/chat-session), so context carries between turns. * **Runs** the target agent on the message and **streams** the reply back to the same thread. * **Stays connected** in the background — most providers use a persistent connection, so there's no webhook URL to host. Channels are scoped to you, not a single space: one account can connect several bots, each pointing a different space's agent at a different audience. Pick a channel [#pick-a-channel] How you connect depends on the provider. QR-based providers are scan-and-go; token providers need a bot token or app credentials from the platform's developer console. | Channel | Best for | How you connect | | ----------------------------------------------- | -------------------------------------- | ---------------------------------------------------------- | | [WhatsApp](/en/docs/channels/whatsapp) | Customer support, sales, lead capture | Scan a QR code (logs in as that account) | | [WeChat](/en/docs/channels/wechat) | Personal WeChat contacts in China | Scan a QR code (logs in as that personal account) | | [Telegram](/en/docs/channels/telegram) | Bots, communities, internal automation | BotFather token | | [Discord](/en/docs/channels/discord) | Developer and community servers | Bot token (Gateway, no webhook) | | [Slack](/en/docs/channels/slack) | Internal team workflows | Bot + app-level token (Socket Mode) | | [Microsoft Teams](/en/docs/channels/msteams) | Enterprise teams on Teams | Azure Bot app credentials | | [WeCom](/en/docs/channels/wecom) | China-based company messaging | Smart Bot ID + secret | | [DingTalk](/en/docs/channels/dingtalk) | China-based company messaging | Scan to auto-register, or Client ID + Secret (Stream Mode) | | [Feishu / Lark](/en/docs/channels/feishu) | Lark/Feishu collaboration | App ID + App Secret (WebSocket) | | [Web chat widget](/en/docs/channels/web-widget) | Your own site or product | Generate an embed snippet | Before you connect [#before-you-connect] * **The target agent already exists.** A channel points at one agent — create and test it first. * **Drive is loaded.** Upload the files the agent should reference so it answers from real context. * **You've picked an audience.** External customers, internal teammates, or both — this shapes your tone and escalation policy. * **You start small.** Connect one agent to one channel, validate the responses on real conversations, then add more. Most providers connect over a persistent connection (Gateway or WebSocket), so you don't need to host a public webhook URL. Microsoft Teams is the exception — it uses a messaging endpoint. Connect a channel [#connect-a-channel] Related [#related] * [Chat session](/en/docs/concepts/chat-session) — how conversations map to sessions * [Agents](/en/docs/getting-started/quickstart) — create the agent a channel points to # Connect Microsoft Teams (/docs/channels/msteams) Bring your agent into Microsoft Teams so colleagues can chat with it in DMs and channels. Teams is the one channel that uses a **messaging endpoint** rather than a persistent connection, so setup runs through Azure — plan about 10–15 minutes. A Teams message answered by a Buda agent Connect the bot [#connect-the-bot] Create an Azure Bot [#create-an-azure-bot] In the [Azure Portal](https://portal.azure.com), search for **Azure Bot** and open the creation page. Set: | Field | Value | | ------------- | ------------------------------- | | Bot handle | e.g. `buda-bot` | | Pricing tier | **Free** (fine for development) | | Type of App | **Single Tenant** | | Creation type | **Create new Microsoft App ID** | Click **Review + create → Create**. Get the credentials [#get-the-credentials] From the Azure Bot resource, collect three values: * **App ID** — **Configuration → Microsoft App ID** * **App Password** — **Manage Password → Certificates & secrets → New client secret**, then copy the **Value** (shown only once) * **Tenant ID** — App registration **Overview → Directory (tenant) ID** Add the channel in Buda [#add-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **Microsoft Teams**. Enter the **App ID**, **App Password** (client secret), and **Tenant ID**, then click **Connect**. Set the messaging endpoint [#set-the-messaging-endpoint] Back in the Azure Bot resource, open **Configuration** and set the **Messaging endpoint** to: ``` https://buda.im/api/channels/msteams/webhook ``` Click **Apply**. Enable the Teams channel and install the app [#enable-the-teams-channel-and-install-the-app] In the Azure Bot resource, open **Channels → Microsoft Teams**, accept the terms, and **Save**. Then in the [Teams Developer Portal](https://dev.teams.microsoft.com/apps), create a new app, add a **Bot** feature with your **App ID** entered manually, check the **Personal / Team / Group Chat** scopes, and **Download app package**. In Teams, go to **Apps → Manage your apps → Upload a custom app** and install the ZIP. Test it [#test-it] Find the installed bot in Teams and send it a DM, e.g. `Hi`. In channels, **@mention** the bot to trigger a reply. Troubleshooting [#troubleshooting] | Symptom | Fix | | ---------------------- | ----------------------------------------------------------------------------------------- | | Bot not responding | Confirm the messaging endpoint is `https://buda.im/api/channels/msteams/webhook` | | App Password expired | Regenerate the client secret in Azure and update Buda's channel settings | | Teams channel inactive | Check **Microsoft Teams** is enabled under Azure Bot → Channels, and the app is installed | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Azure Bot registration guide](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) # Connect Slack (/docs/channels/slack) Put your agent inside your team's Slack — an ops copilot, a support responder, an internal knowledge bot. Buda connects with two tokens over **Socket Mode**, so there's no public webhook URL to host. Once connected, the bot answers in channels and DMs. A Slack message answered by a Buda agent Connect the bot [#connect-the-bot] Create a Slack app [#create-a-slack-app] Go to [api.slack.com/apps](https://api.slack.com/apps), click **Create New App → From scratch**, name it (e.g. `Buda Assistant`), choose your workspace, and click **Create App**. Enable Socket Mode and get the app-level token [#enable-socket-mode-and-get-the-app-level-token] Open **Socket Mode** and toggle it on. When prompted, create an **app-level token**: name it (e.g. `buda-socket`), add the `connections:write` scope, and **Generate**. Copy the token — it starts with `xapp-`. Add bot token scopes [#add-bot-token-scopes] Go to **OAuth & Permissions → Bot Token Scopes** and add: * `app_mentions:read` — receive @mentions in channels * `channels:history` — read channel history * `chat:write` — send messages * `im:history`, `im:read`, `im:write` — read and open DMs * `users:read` — resolve display names Subscribe to events [#subscribe-to-events] Open **Event Subscriptions**, toggle **Enable Events**, and under **Subscribe to bot events** add `app_mention` and `message.im`. Click **Save Changes**. Install and get the bot token [#install-and-get-the-bot-token] Back in **OAuth & Permissions**, click **Install to Workspace** and authorize. Copy the **Bot User OAuth Token** — it starts with `xoxb-`. Configure the channel in Buda [#configure-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **Slack**. Paste both tokens — **Bot User OAuth Token** (`xoxb-`) and **App-Level Token** (`xapp-`) — optionally set a label and **target agent**, then click **Connect**. Start chatting [#start-chatting] * **In a channel:** invite the bot with `/invite @YourBotName`, then @mention it. * **In a DM:** open a direct message and send anything — no @mention needed. Troubleshooting [#troubleshooting] | Symptom | Fix | | --------------------- | --------------------------------------------------------------------------- | | No reply in a channel | Invite the bot first, then @mention it; confirm `app_mention` is subscribed | | No reply in DMs | Confirm `message.im` and the `im:*` scopes are added | | Connection fails | Re-check that both `xoxb-` and `xapp-` tokens are pasted correctly | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Connect Discord](/en/docs/channels/discord) — another Gateway-style, webhook-free channel # Connect Telegram (/docs/channels/telegram) Put your agent in front of users on Telegram — answer DMs, run a support bot, or drop it into a community. Setup takes a few minutes entirely inside Telegram: no developer account, no approval, no webhook to host. A Telegram message answered by a Buda agent Connect the bot [#connect-the-bot] Create a bot with BotFather [#create-a-bot-with-botfather] Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. It asks for two things: * **Display name** — what users see, e.g. `Buda Assistant` * **Username** — must end with `bot`, e.g. `buda_assistant_bot` BotFather replies with a **token** like `1234567890:AAFx...`. Copy it. Add the channel in Buda [#add-the-channel-in-buda] In Buda, open **Settings → Channels**, click **Add Channel**, and select **Telegram**. Paste the token, optionally set a label and **target agent**, then click **Connect**. Test it [#test-it] Search for your bot's username in Telegram, open the chat, and send `Hi`. Once Buda replies, you're connected. Use it in a group [#use-it-in-a-group] Add the bot to a group, then **@mention** it to trigger a reply: ``` @buda_assistant_bot What's on my schedule today? ``` In private chats no mention is needed. Troubleshooting [#troubleshooting] | Symptom | Fix | | ------------------- | ----------------------------------------------------------------------------------------------- | | Bot not responding | Re-copy the token from BotFather (watch for stray spaces); confirm the channel shows **Active** | | No reply in a group | You must @mention the bot in group chats | | Token compromised | Send `/revoke` to BotFather, regenerate, then update the token in Buda's channel settings | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [BotFather guide](https://core.telegram.org/bots/tutorial) # Embed a web chat widget (/docs/channels/web-widget) Turn any agent into a chat widget for your own site — a support assistant, a sales bot, an interactive demo. The web channel gives you a public chat page and a one-line embed snippet; visitors talk to your agent right where they already are, no login required unless you want one. A web chat session with a Buda agent Create a web channel [#create-a-web-channel] Add the channel [#add-the-channel] Open **Settings → Channels**, click **Add Channel**, and select **Web**. Pick the **target agent** that should answer, give it a label, and save. Open its configuration [#open-its-configuration] Select the new web channel to open its config panel. It gives you the public chat link, the embed snippet, and the visitor toggles described below. Embed the widget [#embed-the-widget] Each web channel has two ways to go live: * **Public chat link** — a hosted page at `https://your-buda-domain/c/`. Copy it and share it directly, or link to it from a button. * **Embed snippet** — drop this script into your site's HTML and the widget loads automatically: ```html ``` The config panel generates both with your real domain and channel ID filled in — use the copy buttons rather than typing them by hand. A web channel only serves visitors while it's **active**. If the chat page shows "not found", check the channel status in Settings → Channels. Visitor behavior [#visitor-behavior] Three toggles in the config panel control how visitors experience the widget. They apply instantly. Persistent vs new session [#persistent-vs-new-session] * **Persistent** — a returning visitor lands back in the same conversation, so context carries across visits. Best for ongoing support or a personal assistant. * **New each visit** — every visit starts a fresh [chat session](/en/docs/concepts/chat-session) with no prior history. Best for one-off questions, demos, or kiosks where you don't want one person's chat bleeding into the next. Login required vs anonymous [#login-required-vs-anonymous] * **Anonymous** (default) — anyone with the link can chat without signing in. * **Require login** — visitors must sign in first. Their name appears on the session, which is useful when you want to attribute conversations to real users. Read-only mode [#read-only-mode] Turn on **read-only** to let visitors view an existing conversation without being able to send messages — handy for sharing a finished thread or showcasing an agent's output without opening it up to new input. Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Chat session](/en/docs/concepts/chat-session) — how persistent and new-session modes map to sessions # Connect WeChat (/docs/channels/wechat) Chat with your agent right inside WeChat. Buda connects by scanning a QR code — there's no app to register, no App ID, and no secret to copy. Just scan and start. A WeChat conversation answered by a Buda agent **Scanning the QR code takes over the account.** Connecting WeChat logs Buda in *as* that personal account — anyone who messages it gets an automatic reply, as if the owner sent it. Use a **dedicated WeChat account**, never your personal one. Connect the account [#connect-the-account] Add the channel in Buda [#add-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **WeChat**. There are no credential fields to fill in — optionally set a label, then click **Connect**. A QR code appears on screen. Scan the QR code [#scan-the-qr-code] Scan the on-screen code using the **dedicated** WeChat account. Once you confirm the login in WeChat, the dialog shows **Connected** and the channel becomes active. Test it [#test-it] From a *different* WeChat account, message the connected account with `Hi`. Once Buda replies, you're set. What's supported [#whats-supported] * **Direct messages only.** The connected account replies to 1:1 conversations; there's no group-chat support today. * **Text, images, files, audio, and video** — inbound media is uploaded to the agent's Drive, and the agent can send files, images, and video back. * **`/new`** — send `/new` (optionally followed by a message) to start a fresh agent session in that conversation. Troubleshooting [#troubleshooting] | Symptom | Fix | | --------------------------------------- | ---------------------------------------------------------------------------------------------- | | QR code expired | QR codes are time-limited (a few minutes). Return to channel settings and start the scan again | | Session expired / channel went inactive | WeChat periodically invalidates the login session. Reconnect the channel and scan again | | Used your personal account | Delete the channel, then reconnect and scan with a dedicated account instead | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Connect WhatsApp](/en/docs/channels/whatsapp) — the same QR scan-and-go pattern, for WhatsApp # Connect WeCom (/docs/channels/wecom) Give your team an AI teammate inside WeCom. Buda connects through WeCom's **Smart Bot** over a long connection — employees message the bot in WeCom and Buda replies automatically, with no public webhook to host. Connect the bot [#connect-the-bot] Create a bot [#create-a-bot] In WeCom, tap **Workbench**, then open **Smart Bot**. Open Smart Bot Tap **Create Bot → Manual Creation**. On the creation page, scroll down and click **Create in API Mode**. Switch to API mode Configure the connection and copy credentials [#configure-the-connection-and-copy-credentials] On the API configuration page: 1. Select **Use Long Connection** as the connection method. 2. Copy the **Bot ID**. 3. Click **Click to Get** to reveal and copy the **Secret**. 4. Fill in the bot name, avatar, and visibility scope, then **Save**. Configure connection and copy credentials The Bot ID and Secret can be viewed again at any time — they aren't one-time values. Add the channel in Buda [#add-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **WeCom Smart Bot**. Enter the **Bot ID** and **Secret**, optionally set a label and **target agent**, then click **Connect**. Test it [#test-it] Back in WeCom, find the bot you just created and send `Hi`. Once Buda replies, you're connected. Troubleshooting [#troubleshooting] | Symptom | Fix | | ---------------------------- | -------------------------------------------------------------------------------------------- | | Bot not responding | Re-copy the Bot ID and Secret (watch for stray spaces); confirm the channel shows **Active** | | Connection never establishes | Make sure you selected **Use Long Connection**, not **Use URL Callback** | | Secret compromised | Regenerate the Secret in the WeCom admin console, then update it in Buda's channel settings | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [WeCom Smart Bot developer docs](https://developer.work.weixin.qq.com/document/path/101463) # Connect WhatsApp (/docs/channels/whatsapp) Reach customers where they already chat. Buda connects to WhatsApp by scanning a QR code — the same flow as WhatsApp Web. No Meta Business account, no API application, no paid subscription. A WhatsApp conversation answered by a Buda agent **Scanning the QR code takes over the account.** Unlike token-based channels, connecting WhatsApp logs Buda in *as* that account — anyone who messages the number gets an automatic reply, as if the owner sent it. Use a **dedicated WhatsApp account**, never your personal number. Connect the account [#connect-the-account] Add the channel in Buda [#add-the-channel-in-buda] Open **Settings → Channels**, click **Add Channel**, and select **WhatsApp**. Click **Connect** — a QR code appears on screen. Scan the QR code [#scan-the-qr-code] Scan the on-screen code using the **dedicated** WhatsApp account. When the status shows **Active**, the connection is complete. Test it [#test-it] From a *different* WhatsApp account, message the connected number with `Hi`. Once Buda replies, you're set. WhatsApp won't let an account message itself, so you need a second account to test. Use it in a group [#use-it-in-a-group] Add the connected account to a WhatsApp group and Buda processes **every** message in the group — no @mention required. Troubleshooting [#troubleshooting] | Symptom | Fix | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | QR code expired | QR codes are time-limited. Return to channel settings to generate a fresh one and re-scan | | Connection dropped | Buda reconnects automatically; if it doesn't recover, check the channel status and re-scan | | Used your personal number | In WhatsApp → **Linked Devices**, log out the Buda entry, delete the channel, and reconnect with a dedicated account | Related [#related] * [Channels overview](/en/docs/channels) — how channels route messages to agents * [Connect Telegram](/en/docs/channels/telegram) — another fast, token-free option # Agents and Claws (/docs/concepts/agents-and-claws) The bottleneck for most founders and small teams isn't ideas — it's hands. An **agent** is a pair of those hands: a focused AI worker you recruit once, direct in plain language, and reuse across many jobs. You decide the outcome; the agent does the work. Your agents in the dashboard Agent vs. Claw [#agent-vs-claw] Two words, one idea seen from two angles: * **Agent** — the *role*: an AI employee with a name, a mission, instructions, files, and connected channels. This is what you hire, configure, and review. * **Claw** — the *worker that executes*: the same agent doing real work inside its [cloud computer](/en/docs/concepts/the-cloud-computer). When you watch a Claw run, you're watching your agent read files, browse the web, run code, and commit to Git. > You manage agents. Claws are how those agents get things done. What an agent is made of [#what-an-agent-is-made-of] | Part | Role | | -------------- | ------------------------------------------------------------------------------------------- | | Identity | Name, description, and the job the agent owns | | Instructions | System prompt, behavior rules, and operating constraints | | Cloud computer | An isolated, long-running sandbox the Claw works in | | Drive | The agent's private file workspace and [knowledge base](/en/docs/concepts/drive-and-memory) | | Skills | Extra [capabilities and SOPs](/en/docs/concepts/skills-and-automations) the agent can call | | Channels | External surfaces — WhatsApp, Slack, Telegram — bound to the agent | | Sessions | Independent conversation contexts created as you and others interact | Where an agent sits [#where-an-agent-sits] ```text Space (your company) └─ Agent (an AI employee) ├─ Cloud computer (where the Claw works) ├─ Drive (private files + knowledge) ├─ Skills (reusable SOPs) ├─ Channels (external entry points) └─ Sessions (one per task or conversation) ``` A [Space](/en/docs/concepts/spaces-teams-members) can hold many agents, each focused on a different job — support, finance ops, recruiting, research, coding. What each agent gives you [#what-each-agent-gives-you] Recruiting an agent provisions three things: 1. **A dedicated cloud computer** — isolated CPU, RAM, and persistent SSD for that agent. 2. **A human member seat** — invite one teammate to collaborate with the agent. 3. **Monthly credits added to the Space pool** — credits accumulate at the Space level, not as a per-agent cap. See [credits and billing](/en/docs/concepts/credits-and-billing-model). When to create a new agent [#when-to-create-a-new-agent] Create a separate agent when you need a different knowledge base, a different role or tone, different channel routing, or cleaner isolation between teams. Don't over-split. If it's the same worker doing related jobs (blog, Xiaohongshu, LinkedIn), use multiple [sessions](/en/docs/concepts/sessions-and-tasks) under one agent. Split into a new agent only when identity, permissions, tools, and files all need isolation. Good agent design [#good-agent-design] * Keep one agent focused on one job, with a clear name and mission. * Put only the files it should actually use in its Drive. * Install Skills deliberately instead of turning everything on. * Connect channels after the core behavior is stable. Related [#related] # Credits and the billing model (/docs/concepts/credits-and-billing-model) Running a team of agents shouldn't come with a billing surprise. Buda meters work in **credits** drawn from a few clearly-scoped pools, all shared inside your [Space](/en/docs/concepts/spaces-teams-members) — so you can see exactly what's available and what each run costs, before it adds up. The three pools [#the-three-pools] Credits live in pools that differ by how they refill: | Pool | Refills | Think of it as | | ----------- | -------------------------- | ------------------------------------------- | | **Daily** | Resets every day | A recurring daily allowance | | **Monthly** | Resets each billing period | Your plan's main monthly grant | | **Balance** | Never resets | Top-ups and rewards you've bought or earned | Daily and monthly pools have a reset date and start fresh when it arrives. The balance pool is **total** — it sits there until spent and doesn't expire on a cycle. Buda spends from your renewing pools first and falls back to the balance pool, so recurring allowances are used before credits you've paid for or earned. The usage panel shows each pool, how much is used, the limit, and when it resets. Shared per Space [#shared-per-space] Credits pool at the **Space** level, not per agent. Every [agent](/en/docs/concepts/agents-and-claws) in a Space draws from the same shared balance. Adding an agent contributes its monthly grant to that shared pool rather than creating a separate per-agent cap. ```text Space credit pool (daily + monthly + balance) ├─ Agent A ── spends ──┐ ├─ Agent B ── spends ──┤──→ one shared total └─ Agent C ── spends ──┘ ``` This means a busy agent can use more while a quiet one uses less — the Space budgets as a whole. How usage is metered [#how-usage-is-metered] Metered activity is tracked per Space across a few types — **AI credits** (model work agents do), **storage** ([Drive](/en/docs/concepts/drive-and-memory) used), **posts/content**, and **members**. Each run checks the relevant pool, deducts as it goes, and reports what remains. When a pool is exhausted, that action is blocked until the pool resets or you top up. Rewards vs. Space credits [#rewards-vs-space-credits] * **Space credits** — the daily/monthly grants from your plan plus purchased top-ups, shared by everyone in the Space. * **Rewards** — credits you earn personally (referrals, onboarding, promotions). They sit in your personal balance and can be applied to a Space when you want to contribute them. See [referral](/en/docs/billing/referral) and [redeem](/en/docs/billing/redeem) for how rewards are earned and applied. Related [#related] # Drive & Memory (/docs/concepts/drive-and-memory) Most AI forgets you the moment a chat ends. No memory, no progress, no idea who you are — every conversation starts from zero. Buda's answer is simple: **an agent's memory is just files, and those files live in its Drive.** The more you put there, the less it starts over — and the more it works like *you*. An agent's Drive — its memory — in the workspace Memory is just files [#memory-is-just-files] There's nothing mystical about agent memory. Open any agent, click **Drive**, and you're looking at a real file system — its memory laid out as files and folders. Because it's plain files, your agent's memory is **portable and yours**: it isn't locked inside a model or a vendor. You can copy the whole working directory and take it with you. That reframes the core skill of working with agents: **managing memory is managing files.** Get the files right and everything else follows. The three layers of memory [#the-three-layers-of-memory] Buda keeps memory in three layers, from fleeting to permanent: | Layer | What it holds | Lifecycle | | ------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | **Session memory** | the back-and-forth of the current job | Ephemeral — each new [session](/en/docs/concepts/sessions-and-tasks) starts fresh | | **`MEMORY.md`** | a compact *index* the agent skims before each task | Persists — the summary, not the whole story | | **Drive** | the full archive: documents, past work, transcripts, notes, memory fragments | Durable and [versioned](#persistent-and-versioned) | The key insight is that `MEMORY.md` is **not** all of your agent's memory — it's the condensed table of contents. The real long-term memory is the body of files in Drive; `MEMORY.md` is what the agent reads first to know where to look. Think of Drive as the full archive and `MEMORY.md` as the highlight reel that points back into it. How memory grows [#how-memory-grows] * **Tell it to remember.** Say "remember this" and the agent writes a memory file — no fixed format, capture a moment whenever it's worth keeping. * **Feed it your materials.** Pour in past articles, recordings and transcripts, a case library, prior projects. The more context an agent accumulates, the more its output sounds like yours. * **Shape who it is.** A few standing files define the agent itself: `AGENTS.md` holds its role and rules; `MEMORY.md` holds what it remembers about you and your work. This is what "AI that evolves" actually means in Buda. The model doesn't change — the **files** improve. Clearer Drive materials, a sharper `MEMORY.md`, better rules in `AGENTS.md`, and reusable [Skills](/en/docs/concepts/skills-and-automations) are what turn a generic Claw into something that behaves like a seasoned teammate who knows your business. Agent Drive vs Space Drive [#agent-drive-vs-space-drive] * **Agent Drive** — private to one agent: its own memory and working files. * **Space Drive** — shared across a [Space](/en/docs/concepts/spaces-teams-members), so multiple agents and people hand work off to each other. Persistent and versioned [#persistent-and-versioned] Drive **persists** across sessions and tasks — close everything, come back, and the files (the memory) are still there. Buda keeps file **history** so you can see how a document changed and recover earlier states, and **snapshots** let you capture a known-good point to return to. What to keep in Drive [#what-to-keep-in-drive] Policies and SOPs · brand guidelines · product specs and FAQs · contracts and templates · research notes and datasets · drafts and project briefs · generated assets and past work. When an agent answers, it opens the relevant files and grounds its reply in **your** documents — updating a file is often faster and more reliable than rewriting a prompt. File hygiene [#file-hygiene] * Use clear, business-oriented folder and file names. * Separate drafts from approved source-of-truth files. * Prune outdated documents instead of letting them pile up — clean memory is good memory. Related [#related] # How Buda works (/docs/concepts/how-buda-works) If you treat Buda as a chat box, the pieces feel confusing — Space, Agent, Session, Drive, Skill, Channel. The shortcut is simple: **Buda is not a chat box, it's a company you run.** You set direction; your AI workforce does the work. The Buda dashboard with your agents The loop in one sentence [#the-loop-in-one-sentence] > **Humanity leads · Buda manages · Claws execute.** * **You are the CEO** — you state the outcome you want and review what comes back. * **Buda is the manager** — the Organizer decides what runs, when, and which agent handles it. * **Claws are the workforce** — agents that actually do the work, in parallel, in the cloud. Each agent runs inside its own isolated, long-running [cloud computer](/en/docs/concepts/the-cloud-computer) — files, browser, terminal, and Git — backed by a persistent [Drive](/en/docs/concepts/drive-and-memory) and memory. Nothing runs on your laptop. The end-to-end loop [#the-end-to-end-loop] 1. **You give a task** in plain language inside a [Session](/en/docs/concepts/sessions-and-tasks). 2. **The Organizer plans it** and routes it to the right agent. 3. **A Claw executes** in its cloud computer — reading files, browsing, running code — while you watch every step live. 4. **Results land in Drive** so the next task can build on them. 5. **You review and iterate**, or turn the workflow into a reusable [Skill or Automation](/en/docs/concepts/skills-and-automations). The building blocks [#the-building-blocks] | Concept | Think of it as | What it's for | | -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ | | [Space](/en/docs/concepts/spaces-teams-members) | The company / workspace | Members, roles, shared Drive, shared credits, billing | | [Agent / Claw](/en/docs/concepts/agents-and-claws) | An AI employee | The unit that does the work; owns identity, instructions, and a cloud computer | | [Cloud computer](/en/docs/concepts/the-cloud-computer) | The agent's machine | Isolated, long-running sandbox with files, browser, terminal, Git | | [Session & Task](/en/docs/concepts/sessions-and-tasks) | A meeting / work item | Isolated context for one job or conversation | | [Drive](/en/docs/concepts/drive-and-memory) | The file cabinet | Durable, versioned storage and knowledge base | | [Skill & Automation](/en/docs/concepts/skills-and-automations) | An SOP | Reusable workflows, run on demand or on a schedule | | [Channel](/en/docs/channels) | A reception desk | How outside users reach an agent (WhatsApp, Slack, Telegram…) | The point of these layers is **management boundaries**: what's shared at the company level, what belongs to one agent, what's only valid in the current session, and what's worth saving for reuse. One agent, many sessions [#one-agent-many-sessions] The most common beginner mistake is creating too many agents. Start with **one agent and several sessions** — same employee, different jobs — and only split into a new agent when identity, permissions, tools, or knowledge truly need to be isolated. Decide structure with one question per layer: just this task? → stay in the Session. New platform style? → new Session. Need it later? → save to Drive. Keeps repeating? → make a Skill. Different permissions or knowledge? → new Agent. Where to go next [#where-to-go-next] # Sessions and tasks (/docs/concepts/sessions-and-tasks) Run three jobs in one long chat and the agent gets confused — the customer-service thread bleeds into the blog draft. **Sessions** fix that by giving each job its own isolated context, so your agent stays sharp and on-topic no matter how much is in flight. An agent chat session Session vs. task [#session-vs-task] * **Session** — an independent conversation context with an agent. Its message history is isolated from every other session. One [agent](/en/docs/concepts/agents-and-claws) can run many sessions at once. * **Task** — a unit of work you hand an agent inside a session ("draft the launch post", "reconcile this CSV"). The agent executes it in its [cloud computer](/en/docs/concepts/the-cloud-computer) and reports back. > One task, one session. Keep distinct jobs in distinct sessions and nothing pollutes anything else. Context isolation [#context-isolation] A single channel or agent can hold unlimited concurrent sessions, each with its own memory: ```text Agent: Support ├── Session: Customer A ← isolated context ├── Session: Customer B ← isolated context └── Session: Customer C ← isolated context ``` The agent replying to Customer A has no memory of Customer B. That isolation is what makes Buda safe at scale: private details never leak across conversations, and each reply uses only the right context. The task lifecycle [#the-task-lifecycle] 1. **You start a task** in a session, in plain language. 2. **The agent works** in its cloud computer — you watch each step live. 3. **It may pause and wait for input** when it needs a decision, a missing detail, or your approval to continue. 4. **It completes**, and the result is ready to review — or saved to [Drive](/en/docs/concepts/drive-and-memory) for later. A **waiting-for-input** session isn't stuck — it's asking. The agent surfaces a question or a choice and holds its place until you respond, then picks up exactly where it left off. Resuming and ending [#resuming-and-ending] Sessions persist. Go idle and a session goes dormant; message it again and the **same** session resumes with its context intact. Start a **new** session and you get a clean slate — none of the old context carries over. Use a fresh session when the topic genuinely changes. Sessions vs. Drive [#sessions-vs-drive] A session holds **short-term** context — the back-and-forth of the current job. [Drive](/en/docs/concepts/drive-and-memory) holds **long-term** material. If something from a session should outlive it, save it to Drive; chat history alone isn't durable knowledge. Related [#related] # Skills and automations (/docs/concepts/skills-and-automations) The second time you explain the same workflow to an agent, you've found a Skill. **Skills** capture how a job is done so you never re-explain it; **Automations** decide when it runs. Together they turn one-off instructions into reliable, repeatable SOPs — the difference between a helpful assistant and a real operation. Skills and apps in a Space What a Skill is [#what-a-skill-is] A Skill is a reusable workflow — a packaged SOP an agent can call by name. It isn't another employee; it's a *method* the [agent](/en/docs/concepts/agents-and-claws) uses. Examples: * Generate a PPT from an outline * Rewrite a blog post for Xiaohongshu, LinkedIn, and video * Run a competitive-research process * Process and clean an Excel file A Skill bundles its instructions, and may include scripts the agent runs inside its [cloud computer](/en/docs/concepts/the-cloud-computer). What an Automation is [#what-an-automation-is] An Automation is a Skill (or task) on a **schedule or trigger** — run it every morning, every Monday, or on an event, with no one in the loop. Skills define *how*; Automations define *when*. > Skill = the SOP. Automation = the SOP, running on its own. Where Skills live: scope [#where-skills-live-scope] Every Skill has a **scope** that determines who can use it and how broadly it's shared: | Scope | Lives in | Available to | | ---------- | ------------------------------------------------- | ---------------------------------------------- | | **System** | Built into Buda | Every agent, everywhere — the standard toolkit | | **Agent** | One agent's workspace | Just that agent | | **Space** | A [Space](/en/docs/concepts/spaces-teams-members) | Every agent in the Space | Use **agent** scope for a workflow only one specialist needs, **space** scope to share an SOP across your team, and reach for **system** Skills for common capabilities that ship with Buda. When to make a Skill [#when-to-make-a-skill] If a task happens once, just do it — don't package it. When a workflow keeps repeating ("every finished blog post becomes a Xiaohongshu post, a LinkedIn post, and a video script"), turn it into a Skill so any agent runs it the same way every time. Then attach an Automation if it should run on a schedule. You can also install ready-made Skills from the [Marketplace](/en/docs/marketplace) or author your own — see [create a custom skill](/en/docs/skills/create-custom). Related [#related] # Spaces, teams and members (/docs/concepts/spaces-teams-members) When you run several businesses, clients, or projects, cramming everything into one workspace turns into chaos — mixed files, mixed budgets, mixed permissions. **Spaces** keep each one cleanly separated, so every venture is its own company with its own people, agents, and resources. A Space with teams and members The hierarchy [#the-hierarchy] ```text User ← you, across every company you belong to └─ Space ← one company / workspace ├─ Members ← people, each with a role ├─ Teams ← groups of agents + people for a function └─ Agents ← the AI workforce ``` * **User** — your single account. You can belong to and switch between many Spaces. * **Space** — a company: members, roles, billing, shared Drive, and shared credits live here. This is the collaboration boundary. * **Team** — an optional grouping inside a Space that bundles agents and the people who work with them around a function (support, marketing, ops). * **Agent** — the AI worker that does the job. See [agents and Claws](/en/docs/concepts/agents-and-claws). Spaces are companies [#spaces-are-companies] Treat each Space as a separate company. If you serve multiple clients or run multiple ventures, give each its own Space: ```text Space A: Your own company Space B: Client A's project Space C: Client B's project ``` People, files, agents, budgets, and permissions stay cleanly separated. You switch between them from the workspace switcher — see [switch spaces](/en/docs/spaces/switch-spaces). Members and roles [#members-and-roles] Invite teammates into a Space and assign each a role that controls what they can see and do. Roles govern access to agents, Drive, billing, and settings. For the full breakdown, see [roles and permissions](/en/docs/spaces/roles-and-permissions) and [invite members](/en/docs/spaces/invite-members). What's shared inside a Space [#whats-shared-inside-a-space] Everything in a Space is shared by its members, within their roles: * **Agents** and their work * **Shared Drive** — a Space-level [knowledge base](/en/docs/concepts/drive-and-memory) agents and people can read and write * **Credits** — a single [credit pool](/en/docs/concepts/credits-and-billing-model) all agents draw from * **Space-scoped [Skills and Automations](/en/docs/concepts/skills-and-automations)** * **Channels, connectors, and settings** Credits and Drive pool at the **Space** level, not per agent. Adding an agent contributes monthly credits to the shared pool that any agent in the Space can spend. Related [#related] # The cloud computer (/docs/concepts/the-cloud-computer) Local agent tools chain you to a machine that has to stay awake. Buda gives every agent its own **cloud computer** instead — a real, isolated sandbox that keeps running, keeps your files, and works while your laptop is closed. When an agent executes, this is where it happens. An agent working in its cloud computer What's inside [#whats-inside] Each cloud computer is a full working environment, not a chat sandbox: * **Files** — a persistent SSD workspace (the agent's [Drive](/en/docs/concepts/drive-and-memory)) the agent reads from and writes to. * **Browser** — the agent can open sites, log in, and act on the live web. * **Terminal** — run commands, scripts, and tools just like a developer would. * **Git** — clone, branch, commit, and push to real repositories. You watch all of it live — every file edit, command, and page — in the [agent workspace](/en/docs/agent-workspace). What makes it different [#what-makes-it-different] * **Isolated** — each agent runs in its own sandbox, so one agent's work never touches another's. This is the foundation of safe, parallel multi-agent operation. * **Long-running** — work continues across hours and days; the agent doesn't lose its place when you step away. * **Persistent** — files, installed tools, and Git history survive between tasks. The next session starts where the last left off. * **Sleeps when idle** — an idle computer consumes no resources and wakes on demand, so you only pay for work that's actually happening. Because the computer persists, an agent compounds over time — its Drive fills with materials, its memory accumulates, its repos grow. That's how a Claw starts to feel like a seasoned employee rather than a fresh chat. How it fits together [#how-it-fits-together] ```text Organizer (decides what runs, when, on which computer) ↓ Cloud computer (isolated, long-running sandbox) ↓ Claw — your agent — working across: files · browser · terminal · Git ``` The [Organizer](/en/docs/concepts/how-buda-works) schedules which agent uses which computer and wakes capacity on demand. The cloud computer provides the machine; the [Claw](/en/docs/concepts/agents-and-claws) does the work inside it. Persistence vs. session [#persistence-vs-session] The computer persists; a [session](/en/docs/concepts/sessions-and-tasks) is scoped to one task. Durable artifacts — drafts, code, datasets — live on the computer's Drive and outlast any single session, while a session only carries the short-term context of the conversation it belongs to. Related [#related] # ACP reference (/docs/developers/acp) **Drive a hosted Buda agent from any ACP client, live.** [Agent Client Protocol](https://agentclientprotocol.com) (ACP) is the open standard editors like Zed and JetBrains use to talk to coding agents — normally a local process such as Claude Code or Codex. Buda exposes the same protocol over WebSocket, so any ACP client can connect to an agent running in Buda's own sandbox exactly as if it were a local subprocess: streamed replies, tool-call updates, and session history all flow through the same `session/update` events an ACP client already knows how to render. Endpoint and auth [#endpoint-and-auth] | | Value | | --------------- | ------------------------------------------------------ | | Endpoint | `wss://buda.im/api/acp?agentId=` | | Transport | WebSocket only | | Auth header | `Authorization: Bearer sk_...` | | Query parameter | `agentId` — required, the agent this connection drives | Authentication is **required**. The Bearer token must be a Buda API key (starting with `sk_`) belonging to a user who has access to the requested agent — either the agent's owner or a member of the Space that owns it. A missing or invalid key, or an `agentId` you can't access, closes the connection with a JSON-RPC error instead of establishing it. Treat the `sk_` key like any other secret — keep it out of shared machines and version control. See [Authentication](/en/docs/developers/authentication) for creating and rotating keys. A connection binds to exactly **one** agent for its lifetime — the `agentId` you connect with. To drive a different agent, open a separate connection with a different `agentId`. Connecting from an editor (Zed, JetBrains, ...) [#connecting-from-an-editor-zed-jetbrains-] **As of this writing, Zed's and JetBrains' `agent_servers`-style config only spawns a local process (`command`/`args`) — neither has a native "connect to a remote WebSocket URL" option yet**, even though the underlying ACP spec supports it and Buda implements it. Don't take a JSON snippet with a bare `url` field at face value; it won't work against Zed's actual config schema (`crates/settings_content/src/agent.rs` in Zed's source only defines `Custom { command, args, env, ... }` and `Registry { ... }` — no URL variant). The practical way to bridge a local-process-only editor to Buda's remote agent today is a small stdio↔WebSocket adapter that the editor spawns as its "local command." We verified [`acpremote`](https://vcoderun.github.io/acpkit/acpremote/) (a third-party, MIT-licensed Python package, not maintained by Buda) does exactly this — its `mirror` subcommand connects out to a remote ACP WebSocket and re-exposes it as stdio ACP, with built-in `--bearer-token` support that maps directly onto Buda's auth model: ```bash uv add acpremote # or: pip install acpremote ``` ```json title="Zed settings.json" { "agent_servers": { "buda": { "type": "custom", "command": "acpremote", "args": [ "mirror", "wss://buda.im/api/acp?agentId=your_agent_id", "--bearer-token", "sk_your_api_key" ] } } } ``` We tested `acpremote mirror` against a real Buda dev server directly (raw stdio JSON-RPC in, a correct `initialize` response streamed back out) to confirm the bridge itself works end to end. We have not personally verified the full experience inside Zed's UI, and `acpremote` is third-party — if it stops working, that's ours to re-verify, not officially supported by Buda. For scripting or CI instead of an editor, connect directly with the official [`@agentclientprotocol/sdk`](https://www.npmjs.com/package/@agentclientprotocol/sdk)'s own WebSocket client (`createWebSocketStream`, from `@agentclientprotocol/sdk/experimental/ws-client`) — no bridge needed, since your own code already speaks ACP instead of asking an editor's local-process launcher to. Finding your agent's ID [#finding-your-agents-id] `agentId` accepts the same identifier the REST API returns when you [create an agent](/en/docs/developers/api-claws) (`POST /api/v1/spaces/{spaceId}/agents`), or the id shown in that agent's page in the Buda dashboard. Supported methods [#supported-methods] | ACP method | What it does | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize` | Negotiates protocol version and capabilities. Advertises `loadSession: true`; no image/audio/embedded-context prompt content yet. | | `session/new` | Starts a new session against the connected agent. Reuses the agent's existing sandbox rather than provisioning a new one each time. | | `session/prompt` | Sends a message and streams the reply back as `session/update` notifications (`agent_message_chunk`, `agent_thought_chunk`, `tool_call`, `tool_call_update`) until the turn ends. | | `session/load` | Reattaches to a session by id — resumes an in-flight reply if one is still streaming, or replays the conversation history if not. | | `session/cancel` | Stops an in-flight `session/prompt` run. | Only `text` and `resource_link` prompt content blocks are supported today. Limitations [#limitations] * **WebSocket only.** ACP's Streamable HTTP profile (`POST`/`GET`/`DELETE`) isn't implemented — connect with a WebSocket-capable ACP client. * **No permission prompts yet.** Buda doesn't send `session/request_permission` — every tool call the agent makes during a run is auto-approved. Don't connect an agent to sensitive data if you need a human-in-the-loop approval step; that's on the roadmap. * **One agent per connection.** A single WebSocket drives exactly the agent named in `?agentId=` — open multiple connections to drive multiple agents at once. * **`sk_` keys only.** Session cookies and OAuth tokens aren't accepted on this endpoint. Related [#related] # API Claws (/docs/developers/api-claws) Smartwatches, IoT devices, chat plugins - they all want built-in AI Agents. But running a large model on-device isn't viable: not enough compute, too much power draw, poor results. **API Claws** is built for this. With a few calls to Buda's REST API at `/api/v1`, third-party developers can give their products a cloud-hosted AI Agent with conversation capability and a private knowledge base, waking on demand and consuming zero resources at rest. In practice, you are not integrating a raw model API. You are integrating a **managed Agent capability layer** that already includes model access, runtime, knowledge base, session management, and operational scaling. Who it's for [#who-its-for] * **Smart hardware makers** - watches, earbuds, IoT devices that want a built-in AI assistant * **Software developers** - mini-programs, apps, browser extensions that want to embed AI chat * **SaaS providers** - who want to offer customers an "AI-powered private space" Two common buyer types [#two-common-buyer-types] 1\. Chat apps, SaaS tools, and third-party software [#1-chat-apps-saas-tools-and-third-party-software] If you already have a product with users, conversations, forms, or workflows, API Claw lets you add an AI Agent without building the whole backend stack yourself. Examples: * A chat app that wants to add an AI assistant into every conversation * A customer service SaaS that wants each customer to have a private AI support agent * A browser extension or internal enterprise tool that needs a cloud-based AI worker 2\. Hardware manufacturers [#2-hardware-manufacturers] If you are building a smartwatch, earbuds, a voice terminal, or another connected device, API Claw lets the device connect to a cloud AI brain instead of trying to run the intelligence locally. That means: * The device handles input and output * The Agent runs in the cloud * Upgrades happen server-side instead of through constant firmware complexity How it works [#how-it-works] API Claws request flow A request authenticates with your API Key, resolves to a Space (tenant boundary), reaches the Agent and its Drive (knowledge base), and runs inside a Chat Session — gated by a credit check against the Space's usage balance rather than a per-request rate limit. Each end user gets an independent Chat Session with isolated context. The Agent sleeps when idle and wakes automatically when a message arrives. What you do not need to build yourself [#what-you-do-not-need-to-build-yourself] With API Claw, the developer does **not** need to separately build or operate: * Model configuration and provider switching * Inference machines or GPU infrastructure * Agent runtime and tool sandboxing * File ingestion and knowledge base processing * Session and context management * Tenant isolation for different users or customers * Wake/sleep orchestration for idle agents This is the key value: your team can focus on the product experience, while Buda provides the Agent infrastructure layer behind it. Why not just call an LLM API directly? [#why-not-just-call-an-llm-api-directly] Calling a model API gives you model output. API Claw gives you an operational AI Agent. | | Raw model API | API Claw | | -------------------- | ----------------------------- | -------------------------------- | | Output | Text or structured completion | Agent reply with runtime context | | Sessions | You manage them | Built-in session model | | Knowledge base | You build retrieval | Drive-based knowledge included | | Runtime | You build orchestration | Managed Agent runtime | | Multi-tenant support | You design it | Space-based isolation built in | | Ops | You run it | Managed by Buda | If you are a product company, this difference matters more than model quality alone. API Claw vs OpenClaw [#api-claw-vs-openclaw] OpenClaw is the Agent capability and runtime layer. API Claw is the productized API surface that lets external hardware and software connect to that capability. In simple terms: * **OpenClaw** = the underlying Agent runtime / capability model * **API Claw** = the developer-facing integration layer built on top of it API surface at a glance [#api-surface-at-a-glance] API Claw is easiest to understand as five cooperating API groups: | API group | Main endpoints | What it controls | Use it when | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Space API | `/api/v1/spaces` | Tenant boundary, customer boundary, or device fleet boundary | You need isolation between customers, teams, devices, or paid accounts | | API Agents API | `/api/v1/api-agents` | Implementation-facing hosted Agent collection for the API Claws product | You want a concise developer-facing way to list or provision API Claws with a plain REST resource name | | Agent API | `/api/v1/spaces/{spaceId}/agents` | The managed Claw Agent inside a Space | You want each tenant or product line to have its own assistant role and instructions | | Drive API | `/api/v1/api-agents/{agentId}/drive/files` | Durable knowledge, manuals, policies, state, and long-lived memory | The Agent should keep improving from files instead of receiving the same giant prompt every time | | Chat Session API | `/api/v1/api-agents/{agentId}/sessions`, `/api/v1/api-agents/{agentId}/sessions/{sessionId}` | User conversations, async Agent runs, status, and messages | Your backend can safely hold the main API Key | | Embed API | `/api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls`, `/api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions`, `/api/v1/embed/chat-sessions/...` | Short-lived iframe URL or frontend-safe chat access | A browser, mobile app, mini program, or extension needs to talk to Buda without seeing your main API Key | API Claw has its own hosted iframe surface. Your backend creates a short-lived embed URL: ```http POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls Authorization: Bearer Content-Type: application/json { "externalUserId": "customer-123", "displayName": "Kelly", "ttlSeconds": 3600, "mode": "chat" } ``` The response includes: ```json { "embedUrl": "https://buda.im/embed/api-claw/tsk_abc123#token=SHORT_LIVED_TOKEN", "sessionId": "tsk_abc123", "expiresAt": "2026-05-26T12:00:00.000Z" } ``` Then iframe the returned `embedUrl`: ```html ``` The token lives in the URL hash fragment so it is not sent to the server as part of the initial page request. The page reads the token in the browser and uses it only for `/api/v1/embed/...` JSON calls. When the token expires, create a fresh embed URL from your backend. How application scenarios combine the APIs [#how-application-scenarios-combine-the-apis] Most products use the same lifecycle: provision, seed, run, read, learn, and update. | Scenario | Space strategy | Agent strategy | Drive strategy | Chat strategy | Embed strategy | | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Smart hardware fleet | One Space per customer, fleet, or premium device group | One Agent per device model or assistant role | Manuals, firmware notes, troubleshooting guides, device state snapshots | Device backend starts sessions when the user speaks or a device event occurs | Native app or mini program uses embed tokens; websites use API Claw embed URLs | | WeChat mini program | One Space per merchant, course, customer, or end-user account | One Agent per business function, such as support, tutor, or shopping assistant | FAQs, product catalog notes, policies, lesson plans, user progress | Your backend mints an embed session for the user's `openid` | Mini program calls `/api/v1/embed/chat-sessions/{sessionId}` with the short-lived token | | SaaS copilot | One Space per customer tenant | One Agent per workflow, such as onboarding, reporting, or support | Tenant docs, integration settings, playbooks, historical summaries | SaaS backend starts sessions and stores returned session IDs | Usually server-to-server; iframe only if you want a Buda-hosted chat surface | | Customer support widget | One Space per customer company or brand | One support Agent per brand or queue | Support articles, refund policy, product docs, escalation rules | Your backend creates one embed URL per visitor or account | Use API Claw embed URLs for hosted iframe chat | | Internal enterprise Agent | One Space per department or project | Multiple Agents for ops, sales, research, or engineering | Internal SOPs, meeting notes, runbooks, shared decisions | Internal tools start sessions from buttons, forms, or scheduled jobs | Use server-to-server for tools; use API Claw embed URLs for a quick internal chat page | Rule of thumb: * Put durable knowledge in **Drive**. * Put transient user input in a **Chat Session**. * Put customer or device isolation in **Spaces**. * Put role, behavior, and runtime identity in **API Claws**. Use `/api/v1/api-agents/{agentId}/...` for the main developer flow; the nested `/api/v1/spaces/{spaceId}/agents/{agentId}/...` endpoints remain available when your backend already works from a Space context. * Use **Embed API** only when the caller is a frontend that cannot safely hold your main API Key. Integration steps [#integration-steps] Register a developer account and get an API Key [#register-a-developer-account-and-get-an-api-key] Sign up for a Buda developer account and retrieve your API Key from settings. This key authenticates all OpenAPI calls. Create a Space (tenant) [#create-a-space-tenant] Each of your customers (or each device) maps to one Space. ```http POST /api/v1/spaces Authorization: Bearer Content-Type: application/json { "name": "Acme Device Fleet", "slug": "acme-device-fleet" } ``` Save the returned `spaceId`. Create an Agent inside the Space [#create-an-agent-inside-the-space] ```http POST /api/v1/spaces/{spaceId}/agents Authorization: Bearer Content-Type: application/json { "name": "Watch Assistant", "emoji": "AI", "instructions": "You are a smartwatch assistant. Use Drive files as source of truth. Keep replies short enough for a small screen." } ``` Save the returned `agentId` and `driveId`. Buda also writes the instructions into the Agent's Drive as durable context, so the Agent can keep evolving from files instead of relying only on one prompt. Add durable knowledge to Drive [#add-durable-knowledge-to-drive] If your Agent needs to answer based on product manuals, FAQs, policies, or device-specific state, write those files into its Drive: ```http PUT /api/v1/api-agents/{agentId}/drive/files Authorization: Bearer Content-Type: application/json { "path": "manuals/reset-device.md", "mimeType": "text/markdown", "content": "# Resetting the device\n\nHold the crown for 8 seconds, then confirm on screen." } ``` Files persist across sessions. Updating a file updates what the Agent can use on the next run. The equivalent Space-scoped route, `/api/v1/spaces/{spaceId}/agents/{agentId}/drive/files`, is still available for provisioning systems that already keep both IDs together. Start a conversation [#start-a-conversation] ```http POST /api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions Authorization: Bearer Content-Type: application/json { "message": "How do I reset my device?", "mode": "chat" } ``` Buda returns a `session.id` and starts the Agent run asynchronously. Store that `session.id` if you want to continue the same user's conversation later. Poll the session result [#poll-the-session-result] ```http GET /api/v1/api-agents/{agentId}/sessions/{sessionId} Authorization: Bearer ``` The response includes the session status and messages. Poll until the status becomes `completed`, `waiting_for_input`, `failed`, or `cancelled`. OpenAPI endpoints for API Claw [#openapi-endpoints-for-api-claw] These endpoints are available in the OpenAPI JSON at `/api/v1/openapi.json` and the interactive Swagger UI at `/api/v1/doc`. | Endpoint | Purpose | | -------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `GET /api/v1/spaces` | List Spaces owned by the API key user | | `POST /api/v1/spaces` | Create a tenant Space | | `GET /api/v1/api-agents` | List hosted API Agents visible to the API key user | | `POST /api/v1/api-agents` | Create a hosted API Agent in a Space | | `PATCH /api/v1/api-agents/{agentId}` | Update a hosted API Agent's name, instructions, or config | | `GET /api/v1/spaces/{spaceId}/agents` | List Claw Agents in a Space | | `POST /api/v1/spaces/{spaceId}/agents` | Create a managed Claw Agent with its own Drive | | `GET /api/v1/api-agents/{agentId}/drive/files` | Browse the Agent's durable Drive with the API Agents route | | `PUT /api/v1/api-agents/{agentId}/drive/files` | Create or overwrite a Drive file with the API Agents route | | `GET /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files` | Browse the same Agent Drive with the Space-scoped route | | `PUT /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files` | Create or overwrite the same Drive file with the Space-scoped route | | `GET /api/v1/api-agents/{agentId}/drive/items` | List files and folders in the Agent's Drive | | `POST /api/v1/api-agents/{agentId}/drive/upload-url` | Get a presigned upload URL for a Drive file | | `POST /api/v1/api-agents/{agentId}/drive/confirm-upload` | Confirm a completed Drive file upload | | `POST /api/v1/api-agents/{agentId}/drive/download-url` | Get a download URL for a Drive file | | `POST /api/v1/api-agents/{agentId}/drive/text` | Read a Drive text file's contents directly | | `POST /api/v1/api-agents/{agentId}/drive/rename` | Rename a Drive file or folder | | `POST /api/v1/api-agents/{agentId}/drive/delete` | Delete a Drive file or folder | | `POST /api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions` | Send a message and start or resume an Agent session | | `GET /api/v1/api-agents/{agentId}/sessions` | List sessions for one API Agent | | `POST /api/v1/api-agents/{agentId}/sessions` | Create a session for one API Agent | | `GET /api/v1/api-agents/{agentId}/sessions/{sessionId}` | Read session status and messages | | `PATCH /api/v1/api-agents/{agentId}/sessions/{sessionId}` | Rename a session | | `DELETE /api/v1/api-agents/{agentId}/sessions/{sessionId}` | Delete a session | | `POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/messages` | Send a message to an existing session | | `DELETE /api/v1/api-agents/{agentId}/sessions/{sessionId}/run` | Stop an active session run | | `POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/attachments` | Request a presigned upload URL for a chat attachment | | `GET /api/v1/api-agents/{agentId}/sessions/{sessionId}/stream` | Resume an active session stream | | `POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/chat` | Stream chat using the AI SDK message protocol | | `GET /api/v1/api-agents/{agentId}/scheduled-tasks` | List an Agent's scheduled tasks | | `POST /api/v1/api-agents/{agentId}/scheduled-tasks` | Create a scheduled task for an Agent | | `GET /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}` | Read a scheduled task | | `DELETE /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}` | Delete a scheduled task | | `POST /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}/enable` | Enable a scheduled task | | `POST /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}/disable` | Disable a scheduled task | | `POST /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}/run` | Run a scheduled task immediately | | `GET /api/v1/api-agents/{agentId}/scheduled-tasks/{taskId}/runs` | List a scheduled task's run history | | `POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls` | Create a short-lived hosted iframe URL for API Claw | | `POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions` | Mint a short-lived frontend-safe embed token for native UI | | `POST /api/v1/embed/chat-sessions/{sessionId}/messages` | Send a frontend message using an embed token | | `GET /api/v1/embed/chat-sessions/{sessionId}` | Poll frontend-visible session status and messages using an embed token | Which URL should I iframe? [#which-url-should-i-iframe] For API Claw, your backend should call this OpenAPI endpoint first: ```txt POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls ``` It returns an `embedUrl` like: ```txt https://buda.im/embed/api-claw/{sessionId}#token={shortLivedToken} ``` That exact returned URL is the iframe `src`. Use this when: * You want a ready-made Buda-hosted API Claw chat UI. * You need a link that expires on a schedule. * You are embedding into a website, admin panel, customer portal, or partner console. * Your product backend can refresh the URL before or after expiration. Do not iframe `/api/v1/embed/...`. Those routes are JSON APIs used by the hosted iframe page and by native frontends. For WeChat mini programs, mobile apps, and browser extensions, build your own chat UI and call: ```txt POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions POST /api/v1/embed/chat-sessions/{sessionId}/messages GET /api/v1/embed/chat-sessions/{sessionId} ``` That gives the frontend a scoped, short-lived token without exposing your main Buda API Key. Embedded chat for mini programs [#embedded-chat-for-mini-programs] For WeChat mini programs, mobile apps, browser extensions, or any frontend you do not fully control, do not ship your main Buda API Key to the client. Use the embed flow instead: 1. Your backend calls Buda with the real API Key and mints a short-lived embed token. 2. Your mini program stores only that short-lived token. 3. The mini program sends messages and polls status through `/api/v1/embed/...`. 4. When the token expires, your backend mints a fresh one. Backend: mint an embed session [#backend-mint-an-embed-session] ```http POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions Authorization: Bearer Content-Type: application/json { "externalUserId": "wechat-openid-oABC123", "displayName": "Kelly", "ttlSeconds": 3600, "mode": "chat", "metadata": { "miniProgram": "wechat", "scene": "device-support" } } ``` Return only `token`, `sessionId`, and the required API URLs to the mini program. For an iframe, call `/embed-urls` instead and return `embedUrl`. Mini program: send a message [#mini-program-send-a-message] ```http POST /api/v1/embed/chat-sessions/{sessionId}/messages Authorization: Bearer Content-Type: application/json { "message": "How do I reset my device?", "mode": "chat" } ``` Mini program: poll for replies [#mini-program-poll-for-replies] ```http GET /api/v1/embed/chat-sessions/{sessionId} Authorization: Bearer ``` This gives mini programs a clean native integration path without iframe constraints, third-party cookie issues, or leaked server credentials. Minimal Node.js example [#minimal-nodejs-example] ```ts const API_BASE = "https://buda.im/api/v1"; const headers = { Authorization: `Bearer ${process.env.BUDA_API_KEY}`, "Content-Type": "application/json", }; const space = await fetch(`${API_BASE}/spaces`, { method: "POST", headers, body: JSON.stringify({ name: "Acme Device Fleet" }), }).then((res) => res.json()); const agent = await fetch(`${API_BASE}/spaces/${space.id}/agents`, { method: "POST", headers, body: JSON.stringify({ name: "Watch Assistant", instructions: "Answer from Drive first. Keep replies concise.", }), }).then((res) => res.json()); await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/drive/files`, { method: "PUT", headers, body: JSON.stringify({ path: "manuals/reset-device.md", content: "# Resetting\n\nHold the crown for 8 seconds.", mimeType: "text/markdown", }), }); const started = await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/chat-sessions`, { method: "POST", headers, body: JSON.stringify({ message: "How do I reset my device?", mode: "chat" }), }).then((res) => res.json()); const status = await fetch(`${API_BASE}/api-agents/${agent.id}/sessions/${started.session.id}`, { headers: { Authorization: headers.Authorization }, }).then((res) => res.json()); ``` Building a continuously evolving Drive-based Agent [#building-a-continuously-evolving-drive-based-agent] The useful pattern is not "send everything in every prompt." Let your product treat Drive as the Agent's durable brain: * Write product manuals, policies, release notes, and user-specific state into Drive. * Start each conversation with a small runtime message, such as the user's question or latest device event. * Poll the Chat Session for status and messages. * When your product learns something durable, write it back to Drive as a file. * Let the next run inherit that improved context automatically. This is how a device or third-party app gets an Agent that improves over time: the API call wakes the Agent, the session captures the immediate conversation, and Drive carries forward the durable knowledge. Billing model [#billing-model] Buda charges per Space, not per end user. You purchase Spaces as the developer; how you charge your end users is entirely up to you. Typical model: * You buy Spaces from Buda (volume pricing available) * You charge your end users a subscription or activation fee * The margin is yours Why hardware teams care [#why-hardware-teams-care] For hardware companies, this changes the cost structure: * No need to ship a device powerful enough to run a full AI stack locally * No need to keep a user's laptop or phone acting as the primary runtime * No need to maintain a separate AI backend team just to support one device line Your hardware can stay lightweight while the AI capability keeps improving in the cloud. Analogy: ChatGPT vs OpenAI [#analogy-chatgpt-vs-openai] | | OpenAI | Buda | | --------------------- | --------------------- | ------------------------------------- | | Consumer product | ChatGPT | Buda App | | Developer API | OpenAI API | Buda OpenAPI | | What developers build | Their own AI products | Complete AI spaces with Agent + Drive | The difference: Buda OpenAPI isn't just model inference — it provides a **complete Agent runtime** including knowledge base, session management, and tool-calling capabilities. Why not OpenClaw? [#why-not-openclaw] [OpenClaw](https://openclaw.ai) is a great open-source AI Agent project, perfect for individuals who want to self-host an assistant on their own machine. But for hardware or software developers who need to scale, it's the wrong tool. > For a full comparison, see: [Buda vs OpenClaw](/en/blog/buda-claws-vs-openclaw) | | OpenClaw | Buda | | ---------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | | Purpose | Open-source personal assistant, self-hosted | Commercial enterprise platform, managed service | | Infrastructure | Runs on user's local machine | Self-built Kubernetes cluster (Claw Computer), elastic scaling | | Gateway | Heavy Gateway layer, single-machine bottleneck | No traditional Gateway, lightweight API layer, horizontal scaling by design | | Multi-tenancy | Not supported, each instance is independent | Native multi-tenancy, one API Key manages millions of Spaces | | Token management | User configures their own model | Commercial Token management, predictable, controllable costs | | Isolation | Shares host OS | Each Agent in its own sandbox, container-level isolation | | SLA & support | Community support, no SLA | Enterprise SLA, commercial support | | Best for | Personal use, developer tinkering | Hardware at scale, SaaS integration, commercial deployment | **In one line: OpenClaw is a tool for personal use. Buda is infrastructure developers sell to their users.** If you need to give 100,000 smartwatches each their own AI assistant, you need Buda, not a separate OpenClaw instance running behind every device. FAQ [#faq] **Do end users need a Buda account?** No. End users have no visibility into Buda. Your product proxies all interactions through the API. **Does the Agent consume resources when idle?** No. The Agent sleeps when there are no active conversations and wakes automatically when a message arrives. **Can I configure different Agent instructions for different users?** Yes. Each Space has its own independent Agent configuration. Create separate Spaces and Agents per user as needed. Related [#related] # Authentication (/docs/developers/authentication) **One key unlocks the whole API.** Every request to Buda's REST API, MCP endpoint, and embed flows authenticates with a single API key tied to your account. Create it once in the dashboard, send it as a Bearer token, and you're calling hosted agents in minutes. Create an API key [#create-an-api-key] Open Settings → API Keys [#open-settings--api-keys] In the dashboard, go to **Settings → API Keys** and choose **Create new key**. Name it and set an expiry [#name-it-and-set-an-expiry] Give the key a recognizable name (for example `production-backend`) and pick an expiry: **Never**, **7 days**, **30 days**, **90 days**, or **365 days**. Short-lived keys are safer for testing and CI. Copy the key now [#copy-the-key-now] The full key — prefixed `sk_` — is shown **once**, right after creation. Copy it into your secret store immediately; Buda only stores a masked version afterward, so it can never be revealed again. If you miss the one-time reveal, delete the key and create a new one. There is no way to recover the full value later. Use the key [#use-the-key] Send the key as a Bearer token in the `Authorization` header. The base URL is `/api/v1`. ```bash # Verify your key resolves to your account curl https://buda.im/api/v1/users/me \ -H "Authorization: Bearer sk_your_api_key" ``` ```ts // Node / TypeScript const API_BASE = "https://buda.im/api/v1"; const headers = { Authorization: `Bearer ${process.env.BUDA_API_KEY}`, "Content-Type": "application/json", }; const me = await fetch(`${API_BASE}/users/me`, { headers }).then((r) => r.json()); ``` A valid key resolves to the owning user; a missing or invalid key returns `401 Unauthorized`. Buda records the time of each key's most recent request so you can spot keys that are still in use before deleting them. Rotation and expiry [#rotation-and-expiry] * **Expiry** is set at creation and cannot be extended. To "renew," create a new key and retire the old one. * **Rotate** by creating the replacement first, deploying it, then deleting the previous key — so there's no gap in service. * **Delete** a key any time from **Settings → API Keys**. Deletion is immediate and permanent: in-flight requests using that key start failing right away. Security best practices [#security-best-practices] * **Treat keys like production secrets.** Never hardcode them in frontend or mobile code, and never commit them to a repo. * **Keep environments separate.** Use distinct keys for test, staging, and production so you can revoke one without disrupting the others. * **Never ship your key to a browser.** For client-side agent chat, use short-lived [embed tokens](/en/docs/developers/embed) instead of your `sk_` key. * **Rotate on exposure.** If a key may have leaked, delete it immediately and issue a new one. Related [#related] # Embed agents (/docs/developers/embed) **Give your users a real agent without exposing your secret.** Your backend mints a short-lived embed credential scoped to one session and one external user; the frontend talks to Buda with that credential only. Your `sk_` API key never leaves your server. There are two flavors: * **iframe URL** (`/embed-urls`) — a ready-made, Buda-hosted chat UI you drop into an ` ``` The token rides in the URL **hash fragment**, so it is not sent to the server with the initial page request — the hosted page reads it in the browser and uses it only for embed JSON calls. Generate a native token [#generate-a-native-token] For UIs you fully control, mint a session and ship only the token: ```bash curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-sessions \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "externalUserId": "wechat-openid-oABC123", "displayName": "Kelly", "ttlSeconds": 3600, "mode": "chat" }' ``` Return only `token`, `sessionId`, and the embed API URLs to the client. The client then sends messages and polls replies with the token: ```bash # Send a message curl -X POST https://buda.im/api/v1/embed/chat-sessions/SESSION_ID/messages \ -H "Authorization: Bearer EMBED_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "How do I reset my device?", "mode": "chat" }' # Poll for the agent reply curl https://buda.im/api/v1/embed/chat-sessions/SESSION_ID \ -H "Authorization: Bearer EMBED_TOKEN" ``` Token lifetime and external users [#token-lifetime-and-external-users] * **`externalUserId`** (required) — your own ID for the end user (a customer ID, device ID, or WeChat `openid`). Buda labels the session with it; end users never need a Buda account. * **`ttlSeconds`** — how long the token is valid. Minimum **60**, maximum **86400** (24 hours), default **3600** (1 hour). * **`sessionId`** — pass an existing one to continue a conversation; omit it to start a new session. * **`mode`** — the prompt mode (`chat`, `agent`, `thinking`, or `build-app`). When a token expires, mint a fresh one from your backend. Security [#security] * **Keep your `sk_` key server-side.** Only short-lived embed credentials should reach a browser or device. * **Scope per user.** One embed credential maps to one `externalUserId` and one session — it can't reach your other Spaces or agents. * **Let it expire.** Use the shortest practical `ttlSeconds` and refresh on demand rather than issuing long-lived tokens. * **Tokens are bound to their session.** A token presented for a different `sessionId` is rejected with `403`. Related [#related] # GitHub app (/docs/developers/github-app) **Publish from the repo you already maintain.** Connect the Buda GitHub app once, point it at a repository, and Buda imports the skills and agents inside it as Marketplace listings — then re-syncs them whenever the source changes. No copy-pasting, no manual uploads. Install the GitHub app [#install-the-github-app] Open the Developer Portal [#open-the-developer-portal] Go to the **Developer Portal** and open the **Repos** tab. If no GitHub installation is connected yet, you'll be prompted to connect one. Authorize on GitHub [#authorize-on-github] Buda sends you to GitHub's app-install screen. Choose the account or organization and grant access to **all repositories** or just the **selected repositories** you want to publish from. Return to Buda [#return-to-buda] GitHub redirects back to the Developer Portal (`/developer/repos`) and Buda records the installation against your account. You only do this once — the connection is reused for every repo you add later. The connection is per-user. Reinstalling on GitHub replaces the previous installation automatically. Import a repository [#import-a-repository] With the app connected, add a repo by its GitHub URL and a short description: 1. In **Repos**, choose **Add repo**. 2. Paste the repository URL (for example `https://github.com/your-org/your-skills`) and a description. 3. Save. The repo is created with status **pending** and Buda kicks off the first sync automatically. Buda reads the skills and agents in the repo and turns them into Marketplace companies and listings. The Repos view shows how many companies and listings each repo produced. Sync updates [#sync-updates] When you push changes to a connected repo, re-import them with **Sync** on that repo: * New and changed skills/agents are re-imported. * Items removed from the repo are **unpublished** from the Marketplace, and the sync result reports how many were removed. Sync uses your GitHub installation token, so it can read private repositories you granted access to. Troubleshooting [#troubleshooting] * **No repositories listed.** Make sure the install granted access to the repos you expect. Open the app's settings on GitHub and add the missing repositories, then return and sync. * **Connection silently dropped.** If GitHub returns a 404 for your installation (for example, the app was uninstalled or access revoked), Buda clears the stale installation and shows an empty repo list. Reconnect from the Repos tab. * **A listing didn't update.** Run **Sync** again — imports run in the background after create, so a failed first pass is fixed by an explicit re-sync. * **A removed item is still listed.** Sync the repo; removed items are unpublished on the next successful sync. Connect GitHub to a specific Agent [#connect-github-to-a-specific-agent] This page covers the **per-user** connection used by the Developer Portal. Agents have a separate, **per-Agent** GitHub connection that's unrelated to Marketplace publishing — it's what lets an Agent's cloud computer read (and, depending on the permissions you grant, push to) real repositories during chat and task runs. * **Connect** — open the Agent, then either click the **+** menu in the chat composer → **Integration** → **OAuth** → **GitHub** (shows **Install GitHub App** until it's connected), or open the Agent's **Integrations** settings and click **Connect** next to GitHub. Both paths send you through GitHub's install screen to pick the account/org and repositories to grant. * **Shared by the whole chat** — the installation is tied to the Agent, not to you personally. Everyone who can chat with that Agent uses the same GitHub access; only an **editor** (or owner) of the Agent can connect, replace, or disconnect it. * **One installation per Agent** — connecting again replaces whatever was connected before for that Agent. * **Disconnect** — from the Agent's Integrations settings, open the GitHub row's menu and choose **Disconnect**. This only forgets the installation on Buda's side; the GitHub App itself stays installed until you remove it from GitHub. There's no confirmation prompt, and disconnecting immediately cuts off access for everyone chatting with that Agent. This Agent-level connection is completely separate from the per-user connection described above — different installation, different table, different purpose. Connecting GitHub for an Agent does not give you Developer Portal / Marketplace publishing access, and connecting the Developer Portal doesn't give any Agent repo access in chat. See [Git](/en/docs/agent-workspace/git-tab) for how the Agent uses this connection to work with real repositories. Related [#related] # Developers (API) (/docs/developers) **Everything Buda does in the dashboard, you can do from your own code.** Provision agents, give them tasks, read their output, and embed live agent chat into your product — all over a stable REST API, with no inference infrastructure to run yourself. What you get [#what-you-get] The same CEO → Organizer → Claws model from the [Buda overview](/en/docs/index) is available programmatically. Your code is the CEO: it directs hosted **Claws** (agents) that execute in their own cloud computers, each with a persistent **Drive** and memory. * **REST API** at `/api/v1` — contract-first, with auto-generated OpenAPI and Swagger. * **API keys** prefixed `sk_` — one Bearer token, scoped to your account. * **API Claws** — hire and run hosted agents, write to their Drive, start sessions, and poll results. * **Embeds** — drop a live agent chat into a website, mobile app, or mini program without leaking your key. * **MCP** — connect Buda to any MCP-compatible client (Claude, Cursor, and more) over the same API. * **GitHub app** — connect repositories to publish skills and agents to the Marketplace. Start here [#start-here] The base URL is `/api/v1` (for example `https://buda.im/api/v1`). Authenticate with an `sk_` key as a Bearer token. Start with [Authentication](/en/docs/developers/authentication). # MCP reference (/docs/developers/mcp) **Let any MCP client operate your Buda account.** Buda exposes a Model Context Protocol (MCP) server that wraps the `/api/v1` REST API as MCP tools. Point Claude, Cursor, or any MCP-capable client at it, authenticate with your API key, and the client can list agents, start sessions, manage Drive, and read results — using the exact same operations as the REST API. If you just want to wire up Claude Desktop step by step, see [MCP with Claude](/en/docs/integrations/mcp). This page is the technical reference. Endpoint and auth [#endpoint-and-auth] | | Value | | ----------- | ------------------------------ | | Endpoint | `https://buda.im/api/mcp` | | Transport | HTTP (Streamable HTTP) | | Auth header | `Authorization: Bearer sk_...` | | Server name | `Buda MCP` | Authentication is **required**. The Bearer token must be a Buda API key (it must start with `sk_`); any other value is rejected. The key resolves to your account exactly as it does for the REST API, and Buda records the key's last-request time on each call. ```json { "mcpServers": { "buda": { "url": "https://buda.im/api/mcp", "headers": { "Authorization": "Bearer sk_your_api_key" } } } } ``` Treat the MCP config like any other place your `sk_` key lives — keep it out of shared machines and version control. See [Authentication](/en/docs/developers/authentication) for rotation and security. Available tools [#available-tools] Buda's MCP tools are **generated directly from the REST API contract**, so the tool set always matches the live `/api/v1` surface. Each REST operation becomes one MCP tool with the same inputs and outputs. That includes, among others: * **Users** — read the authenticated account (`/users/me`). * **Spaces** — list and create Spaces (tenants). * **Agents** — list and create hosted Claw agents. * **Drive** — list, read, and write agent Drive files. * **Sessions** — create sessions, send messages, read status and replies, cancel runs. * **Scheduled tasks** — list, create, enable/disable, and run agent scheduled tasks. For the authoritative, always-current list of tools and their exact schemas, browse the source contract in the [Swagger UI](/api/v1/doc) or [OpenAPI JSON](/api/v1/openapi.json) — every operation there is exposed as an MCP tool. Limitations [#limitations] * **One credential type.** The MCP endpoint accepts `sk_` API keys only; embed tokens and session cookies are not valid here. * **Account scope.** Tools act on whatever the API key can access — the same permissions as the REST API, no more. * **Streaming chat.** MCP tools start and read agent runs; live token-by-token streaming is served by the REST stream endpoints rather than MCP. Related [#related] # Model API (/docs/developers/model-api) **Point your OpenAI client at Buda.** `POST /api/v1/responses` speaks the OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses) wire format — the same one OpenAI Codex CLI and other newer OpenAI-ecosystem tools use by default. Set your tool's base URL to Buda and your API key to a Buda `sk_` key, and it works without writing any Buda-specific integration code. This is the raw model API — one call in, one model reply out, billed per call. If you want a hosted agent with its own Drive-based knowledge, session history, and multi-step runtime instead, see [API Claws](/en/docs/developers/api-claws). Base URL [#base-url] ``` https://buda.im/api/v1 ``` Configure your client's base URL to the value above and its API key to a Buda `sk_` key — see [Authentication](/en/docs/developers/authentication) to create one. Supported models [#supported-models] Buda gives you one endpoint in front of many model families — pick whichever fits the task, or let Buda pick for you. | Model | Family | | --------------------- | ------------------------------------------ | | `claude-haiku-4-5` | Claude | | `claude-sonnet-5` | Claude | | `claude-opus-5`\* | Claude | | `claude-fable-5`\* | Claude | | `gemini-3.1-pro` | Gemini | | `gemini-3.1-flash` | Gemini | | `gemini-3.7-flash` | Gemini | | `gpt-5.6-sol`\* | GPT | | `gpt-5.6-terra` | GPT | | `gpt-5.6-luna` | GPT | | `deepseek-v4-flash`\* | DeepSeek | | `deepseek-v4-pro`\* | DeepSeek | | `auto` | Buda picks a current default model for you | \* Gated to specific subscription plans; an ungated request for one of these falls back to a default model. Use Buda's model IDs above in the `model` field, not OpenAI's own model names (`gpt-4o`, etc.) — Buda doesn't proxy to OpenAI's model catalog, it routes to its own. Example: a single reply [#example-a-single-reply] ```bash curl -X POST https://buda.im/api/v1/responses \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "input": "Say hello in exactly three words." }' ``` ```json { "id": "resp_...", "object": "response", "status": "completed", "model": "claude-sonnet-5", "output": [ { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "Hello there, friend!" }] } ], "usage": { "input_tokens": 12, "output_tokens": 5, "total_tokens": 17 } } ``` Example: streaming [#example-streaming] Set `"stream": true` to get the reply as it's generated, as standard OpenAI Responses API server-sent events (`response.created`, `response.output_text.delta`, `response.completed`, ...): ```bash curl -N -X POST https://buda.im/api/v1/responses \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "input": "Say hello in exactly three words.", "stream": true }' ``` Example: system instructions and multi-turn context [#example-system-instructions-and-multi-turn-context] `instructions` sets the system prompt for the call; `input` also accepts a full message array instead of a single string when you need to pass prior turns yourself: ```bash curl -X POST https://buda.im/api/v1/responses \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "instructions": "Reply in Simplified Chinese.", "input": [ { "role": "user", "content": "What is Buda?" }, { "role": "assistant", "content": "Buda is an AI agent platform." }, { "role": "user", "content": "Summarize that in one sentence." } ] }' ``` Each call is stateless — Buda doesn't keep server-side conversation state between calls (no `previous_response_id`). If you need multi-turn history, send it back yourself as shown above. Using it with OpenAI Codex CLI [#using-it-with-openai-codex-cli] Codex CLI now requires `wire_api = "responses"` for custom providers, which is exactly what this endpoint speaks. Add a provider to `~/.codex/config.toml`: ```toml [model_providers.buda] name = "buda" base_url = "https://buda.im/api/v1" wire_api = "responses" env_key = "BUDA_API_KEY" ``` ```bash BUDA_API_KEY=sk_your_api_key codex --model claude-sonnet-5 -c model_provider=\"buda\" ``` What's not supported yet [#whats-not-supported-yet] This first version covers plain text in, text out. Not yet available: function/tool calling, image or file inputs, and the `GET /v1/models` listing endpoint. If your use case needs one of these, use the model IDs from the table above directly and check back — this surface is actively growing. Billing [#billing] Every call is billed in AI credits against your own account, the same pool used by [API Claws](/en/docs/developers/api-claws) — not a shared quota. See [What are credits](/en/docs/billing/credits) for how the credit pools work, and top up if a call returns `429 insufficient_quota`. Related [#related] # REST API (/docs/developers/rest-api) **Call Buda from any language.** The REST API at `/api/v1` is contract-first: every endpoint is defined by an oRPC contract, so the OpenAPI spec and Swagger UI are always in sync with what the server actually does. Use it from a backend, a CI job, a non-TypeScript client, or generated SDKs. Explore the API [#explore-the-api] * **Swagger UI** (`/api/v1/doc`) — test calls live with your API key. * **OpenAPI JSON** (`/api/v1/openapi.json`) — feed it to `openapi-generator`, Postman, Insomnia, or contract tests. * **buda-cli** ([github.com/buda-ai/buda-cli](https://github.com/buda-ai/buda-cli)) — the official Rust CLI, no SDK generation needed. There's currently no TypeScript/JS SDK; use the OpenAPI JSON with your generator of choice if you need one. TypeScript clients can also generate types directly from the exported oRPC contract instead of from the JSON spec. Authentication [#authentication] Every protected endpoint expects an `sk_` API key as a Bearer token: ```bash curl https://buda.im/api/v1/api-agents \ -H "Authorization: Bearer sk_your_api_key" ``` A missing or invalid key returns `401 Unauthorized`. See [Authentication](/en/docs/developers/authentication) to create and manage keys. Quick start [#quick-start] Health check (no auth) [#health-check-no-auth] ```bash curl https://buda.im/api/v1/health ``` ```json { "status": "ok", "timestamp": "2025-01-01T00:00:00.000Z" } ``` Who am I? [#who-am-i] ```bash curl https://buda.im/api/v1/users/me \ -H "Authorization: Bearer sk_your_api_key" ``` Create a Drive-based Claw agent [#create-a-drive-based-claw-agent] ```bash curl -X POST https://buda.im/api/v1/api-agents \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "spaceId": "YOUR_SPACE_ID", "name": "Watch Assistant", "instructions": "Use Drive files as source of truth and keep replies concise." }' ``` Add knowledge to the agent Drive [#add-knowledge-to-the-agent-drive] ```bash curl -X PUT https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/drive/files \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "path": "manuals/reset-device.md", "content": "# Resetting\n\nHold the crown for 8 seconds.", "mimeType": "text/markdown" }' ``` Start a session and poll for the reply [#start-a-session-and-poll-for-the-reply] ```bash # Send a message — the agent run starts asynchronously (202) curl -X POST https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "message": "How do I reset my device?", "mode": "chat" }' # Poll the session until status is completed / waiting_for_input / failed / cancelled curl https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions/SESSION_ID \ -H "Authorization: Bearer sk_your_api_key" ``` Endpoint groups [#endpoint-groups] The API is organized into a few cooperating groups, all under `/api/v1`: | Group | Base path | What it does | | --------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | System | `/health`, `/meta` | Liveness and service metadata (no auth on `/health`). | | Users | `/users/me` | The authenticated key owner. | | API Claws | `/api-agents`, `/spaces`, `/spaces/{id}/agents`, `.../drive/files`, `.../sessions` | Provision Spaces and hosted agents, manage Drive, run and read sessions, schedule tasks. | | Embed | `.../embed-urls`, `.../embed-sessions`, `/embed/chat-sessions/{id}` | Short-lived iframe URLs and frontend-safe tokens. | For the full request/response shapes, use the live [Swagger UI](/api/v1/doc) or the [OpenAPI JSON](/api/v1/openapi.json). Related [#related] # Create an account (/docs/getting-started/create-account) Creating an account takes under a minute and there's nothing to install. The moment you sign up, you get a **Space** (your workspace) and your first agent is one click away. Go to sign-up [#go-to-sign-up] Open [buda.im](https://buda.im) and choose **Sign Up**. No credit card is required to start. Pick how you sign in [#pick-how-you-sign-in] * **Email and password** — enter your name, email, and a password (at least 8 characters). * **GitHub** — one-click OAuth with your GitHub account. * **Google** — one-click OAuth with your Google account. Social sign-in is the fastest path: you skip password setup and email verification. On WeChat, Buda also offers a Mini Program login that signs you in with your WeChat account. The web sign-up page itself uses email, GitHub, and Google. Verify your email [#verify-your-email] If you signed up with email and a password, Buda sends a verification link to your inbox. Open it to confirm your address, then return to sign in. GitHub and Google accounts are already verified, so they skip this step. Don't see the email? Check spam, and make sure the address is spelled correctly. You can request a new link from the **Check your email** screen. First-run onboarding [#first-run-onboarding] After your first sign-in you land in your dashboard, where a short welcome wizard helps you get oriented: 1. A quick intro video on how Buda works. 2. The **company model** — how you act as CEO while agents do the work. 3. A one-tap choice of what you want to do first (create something, explore the dashboard, invite your team, or just look around). Your answer tailors the **Get started** checklist on your dashboard. You can dismiss the wizard at any time and revisit the checklist later. What you get on day one [#what-you-get-on-day-one] * A personal **Space** that works like your own company. * Credits to run your first agents (see [Credits and the billing model](/en/docs/concepts/credits-and-billing-model)). * Access to the [Marketplace](/en/docs/marketplace) to install skills and hire pre-built agents. Next steps [#next-steps] # Run and review your first task (/docs/getting-started/first-task) A task is one unit of real work you hand to an agent. Get this loop right — *prompt, watch, answer, iterate* — and you can delegate almost anything. This page walks through a full task end to end. A completed agent task with output Write a clear task prompt [#write-a-clear-task-prompt] Agents do best with a clear outcome, not a vague wish. A strong prompt usually names three things: * **The goal** — what "done" looks like. * **The context** — files, links, or constraints the agent should use. * **The format** — a doc, a table, an email, code, a published page. > **Weak:** "Help with our pricing." > > **Strong:** "Write a pricing page with three tiers (Starter, Pro, Team), a feature-comparison table, and a clear CTA. Match the tone of the homepage. Output it as a draft I can review." You can attach files for the agent to use as context. Keep one task focused on one outcome — start a new task for unrelated work. Follow the live steps [#follow-the-live-steps] Once you send the prompt, the agent goes to work in its **cloud computer** and you can watch each step as it happens: * **Files** — it reads inputs and writes drafts, documents, or code. * **Browser** — it opens pages to research or verify facts. * **Terminal** — it runs commands when a task needs them. * **Git** — it tracks changes so work is versioned and reviewable. Each step is shown in the session timeline, so you always know *what* the agent did and *why*. Handle waiting-for-input [#handle-waiting-for-input] Sometimes an agent needs a decision only you can make — a choice between options, a missing detail, or permission to proceed. When that happens, the task **pauses and asks** instead of guessing. Just reply in the chat to unblock it, and it picks up exactly where it left off with full context. There's no penalty for stepping away: a paused task waits for you. Long task running? You can leave and come back. Execution continues in the cloud, and the session is right where you left it. Review and iterate [#review-and-iterate] When the task completes, review the output in the session. Open any file it produced, check the steps it took, and decide what's next: * **Good enough?** Use it, publish it, or download it. * **Almost there?** Reply with specific feedback — *"tighten the intro and add a comparison row for support"* — and the agent revises in place. * **Worth repeating?** Turn a task you'll run again into a reusable [Skill](/en/docs/skills) or a scheduled [Automation](/en/docs/skills/automations). Iteration keeps the full history, so you can always see how the deliverable evolved. Tips for better results [#tips-for-better-results] * **One outcome per task.** Split big asks into separate tasks you can review independently. * **Show, don't just tell.** Attach examples or reference files when format matters. * **Front-load constraints.** Tone, length, and audience are easier to set up front than to fix after. Related [#related] # Quickstart — hire your first agent (/docs/getting-started/quickstart) The fastest way to understand Buda is to put an agent to work. In about five minutes you'll recruit your first agent, hand it a task in plain language, and get back a real deliverable — all in the cloud, nothing installed.