# Files
Files in Nebula live in your workspace — you upload them, agents create them, and both you and your agents work with them. You can preview a file, download it, reference it in chat, or share it with a public link.
Where files come from [#where-files-come-from]
Drop a file straight into a thread — click the **paperclip** in the message box, paste from your clipboard, or drag and drop onto the conversation. Files up to **100 MB** each are supported.
When an agent runs code, generates a document, or saves a result, that file lands in the thread too — tagged with the agent that made it, so you know where it came from.
Finding and viewing files [#finding-and-viewing-files]
Every thread has a **Files** tab in its activity panel, next to Browser and Terminal. It lists what's been added — grouped by type (images, video, audio, documents, data, spreadsheets), each with its name and when it landed.
Click any file to open it full-screen. Nebula renders it inline based on what it is:
Pan and zoom — jpg, png, gif, svg, webp, and more.
Play right in the viewer; audio is transcribed automatically.
PDFs and text files preview inline.
JSON, CSV, YAML, SQL, and dozens of other formats render with syntax highlighting.
Excel, ODS, and Parquet files download rather than preview — they're not text, so there's nothing useful to render.
From the file view you can **Download** it to your device, **Share** it (below), or close back to the thread. To point an agent at a file mid-conversation, type **`@file:`** and pick it — see [Replying & mentioning](/docs/channels/threads#replying--mentioning).
When an agent mentions a file in its reply, it comes through as a pill you can click to open. It's a real link, so middle-clicking or opening it in a new tab works the way you'd expect. A pill for a file that no longer exists sits there as plain text rather than leading you somewhere broken.
Sharing a file [#sharing-a-file]
Two separate ideas live here: who *inside* your workspace can see a file, and a public link for people *outside* it.
Workspace visibility [#workspace-visibility]
A file's visibility follows where it was created. A file added in a **workspace channel** is shared with the whole workspace — it carries a **Shared with workspace** badge. A file added in a **DM or private channel** stays **private to you**, so a teammate's agents can't reach it.
Public share link [#public-share-link]
To hand a file to someone outside Nebula, open it and click **Share** — *"Create public share link."* Nebula generates a public URL and copies it to your clipboard.
A share link is public — **anyone with the link can open the file**, no Nebula account needed. Only create one for files you're comfortable making accessible to anyone who has the URL.
Need to change who can see a file, or revoke a link? Ask Nebula in chat — and for anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# For AI Agents
Nebula's documentation is available in machine-readable formats so AI agents, coding assistants, and LLMs can use it as context.
Endpoints [#endpoints]
| Endpoint | What it returns |
| ---------------------------------- | ----------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt) | Categorized index of all pages with descriptions and `.mdx` links |
| [`/llms-full.txt`](/llms-full.txt) | Complete documentation as a single markdown file |
| `/docs/[page].mdx` | Any individual page as markdown (append `.mdx` to the URL) |
llms.txt [#llmstxt]
The [`/llms.txt`](/llms.txt) file follows the [llmstxt.org](https://llmstxt.org/) specification. It provides a structured index of every documentation page, grouped by section, with links to the markdown version of each page. Use this when you need the AI to pick which pages are relevant before fetching the full content.
llms-full.txt [#llms-fulltxt]
The [`/llms-full.txt`](/llms-full.txt) file contains the entire documentation site as a single markdown file. Use this when you want to give an LLM the full context in one shot — for example, as a system prompt for a docs assistant.
Per-page markdown [#per-page-markdown]
Append `.mdx` to any docs URL to get the raw markdown. For example:
[`/docs/getting-started/quickstart.mdx`](/docs/getting-started/quickstart.mdx) — the Quickstart guide as markdown.
[`/docs/agents/capabilities.mdx`](/docs/agents/capabilities.mdx) — what agents can do (tools + permissions), as markdown.
Using with coding assistants [#using-with-coding-assistants]
Claude Code [#claude-code]
Point Claude Code at the full docs:
```
Fetch https://docs.nebula.gg/llms-full.txt and use it as context for answering questions about Nebula.
```
Cursor / Windsurf [#cursor--windsurf]
Add the docs URL as a context source in your project settings:
```
https://docs.nebula.gg/llms-full.txt
```
Custom agents [#custom-agents]
If you're building an agent that answers questions about Nebula, fetch `/llms-full.txt` and inject it as the system prompt. Here's the pattern:
```
System: You are a Nebula documentation assistant. Answer questions
using ONLY the following documentation. Be concise and helpful.
If the answer isn't in the docs, say so.
{contents of /llms-full.txt}
```
Ask AI [#ask-ai]
The documentation site includes a built-in AI assistant powered by the full docs context. Click the **Ask AI** button in the bottom-right corner of any page to ask questions about Nebula. The assistant uses `/llms-full.txt` as its knowledge base.
Related [#related]
# Nebula Documentation
Nebula is an AI you talk to. Tell it what you need — research, writing, coding, posting to Slack, managing Twitter — and it does the work. When you're ready, make it run on autopilot. These docs walk you through everything from your first message to running a workspace with multiple teammates and dozens of automations.
Start here [#start-here]
What you can do [#what-you-can-do]
Nebula isn't a single chat bot — it's a workspace where AI agents, channels, automations, and a cloud device come together. A few of the things teams build with it:
Research, code review, monitoring, customer support triage, content drafting — anything an LLM can do, with the tools to act on it. See [Agents](/docs/agents).
Topic-based rooms, each with auto-summarized threads so anyone joining late sees the recap. See [Channels & threads](/docs/channels).
Daily digests, hourly checks, weekly reports — Nebula handles the cron. See [Triggers](/docs/jobs).
4,000+ apps via OAuth — Slack, GitHub, Notion, Gmail, Stripe, Linear, Salesforce. See [Integrations](/docs/tools).
Go deeper [#go-deeper]
Built for one person or a whole team [#built-for-one-person-or-a-whole-team]
Every account starts with a personal workspace. The moment you invite someone, it's a team workspace — same surface, just with more people sharing the agents, channels, miniapps, and devices. Switch between workspaces from the workspace dropdown at the top of the sidebar; each one has its own settings, billing, and connected apps.
Not sure where to start? Just ask Nebula — it can answer questions about its own features, walk you through setup, and even configure things for you.
# Jobs
A job runs an agent automatically — on a schedule, when something happens in a connected app, or from an incoming webhook. Find your jobs in the **Jobs** row in the sidebar, or just tell Nebula when to repeat any task. The mechanism behind every job is a trigger; there is no separate automation system to learn.
Three trigger types [#three-trigger-types]
Every weekday at 9am, every Monday, the first of the month. Say the cadence; Nebula handles the cron.
Fire when something happens in a connected app — a Slack message, a Twitter mention, a Discord post.
Accept payloads from Zapier, Make, Stripe, or anything that can POST.
Creating a trigger [#creating-a-trigger]
After any task, just say when to repeat it. Nebula creates the trigger and runs it from then on.
It works the same for events and webhooks:
Scheduled triggers [#scheduled-triggers]
Say it in plain English — *"every weekday at 9 AM"*, *"every Monday morning"*, *"once a day at 5 PM Eastern"* — Nebula picks the right cron and the right timezone. Schedules can run as frequently as **once every 15 minutes**.
For specific intervals, use one of the presets or write a custom cron:
| Preset | Cron |
| ------------------- | -------------- |
| Every 15 minutes | `*/15 * * * *` |
| Every hour | `0 * * * *` |
| Daily at 9:00 AM | `0 9 * * *` |
| Weekdays at 9:00 AM | `0 9 * * 1-5` |
| Weekly on Monday | `0 9 * * 1` |
| Monthly on the 1st | `0 9 1 * *` |
Open the trigger details panel and pick **Custom cron…** to enter any valid expression. Useful for non-standard intervals like "every 3 hours" or "twice daily at 8 AM and 6 PM".
Event triggers [#event-triggers]
Connect Slack, Discord, Telegram, or Twitter to your workspace and Nebula can react to events from those platforms in real time.
New message, reaction added or removed, file shared, channel created / archived / renamed, member joined or left, pin added or removed, emoji changed.
Reaction added or removed, member joined or left, channel created or deleted.
New message, photo / video / audio / voice, document, member joined or left.
New tweet, tweet liked, follow or unfollow, block or mute, direct message.
Narrow which events fire your trigger with filters: specific channels (`channel_ids`), specific users (`user_ids`), or text patterns (`text_contains`). Combine multiple filters to be as specific as you need.
Each event type has its own filter fields. For Slack messages: channel, user, regex on body. For GitHub: repository, label, author. Nebula prompts for the filters that make sense for the event you picked.
Webhook triggers [#webhook-triggers]
Webhook triggers give you a unique URL any external service can POST to. Useful when Nebula doesn't have a native integration but the service can send outbound webhooks — Zapier, Make, Stripe, CI/CD pipelines, monitoring tools.
Ask Nebula for one —
*"give me a webhook that files a bug when my monitor fires"*
. There's no trigger-type picker to hunt for; the
**Create job**
button on the Jobs page makes a job from a name and a description, and webhooks come from the conversation.
Nebula generates a unique URL and shows it in the job's details, under
**Webhook**
. Copy it from there.
Paste it into the source service. Any HTTP POST to that URL fires the trigger, and the request body is passed to the task as context.
Webhook URLs are secrets — anyone with the URL can fire the trigger. Treat them like an API key. Rotate from the trigger panel if needed.
Need help setting up a trigger? Ask Nebula directly in chat first — it can create, pause, and edit triggers for you. For bugs or anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Where triggers live [#where-triggers-live]
Every trigger has two parts:
**A trigger condition**
— the schedule, event, or webhook that starts it.
**A task recipe**
— the prompt and execution steps Nebula follows, including which agents handle each step and where to deliver the result.
Open any trigger from the **Jobs** page, or from an agent's details panel, to see and edit the description, condition, delivery channel, prompt, execution steps, and activity log.
Tracking your jobs [#tracking-your-jobs]
The **Jobs** page lists every job as a summary card so you can see the state of your automations at a glance.
Each card carries a status badge — **Running**, **Scheduled**, **Failed**, **Paused**, or **Idle**.
Cards show the latest run's summary, the agent and channel handling it, and when it runs next.
A job that's working right now shows a pulsing indicator with its most recent step, and the **Jobs** row in the sidebar gets a dot while any job is in flight.
Goal rows are clickable — open the job behind a goal straight from where it appears.
The run count on a card counts times the job *fired*, not times it succeeded — a job that has failed every attempt still reads **4 runs** rather than sitting at zero. That matters if you capped a job with a run limit, because failed attempts spend it too, and a job that never works will eventually run itself out and switch off.
Every job also keeps its own thread, and that's where its results land — including when you run it by hand, which delivers into the job's thread rather than the conversation you asked from. Nothing a job produces arrives in your Nebula DM.
Use the **status filter** to focus the list — it's multi-select, so you can show any mix of Running, Scheduled, Failed, Paused, and Idle.
**Paused** jobs are hidden by default so the list shows what's live. Tick **Paused** in the status filter to see them, or **Clear filters** to return to the default view.
If a job's last run stopped to ask you something and you haven't answered, the next scheduled fire is skipped rather than started — the run history records that it was waiting on your input. Answer the card and the job picks up its normal cadence from the next fire. That's why a job can look idle at a time it should have run.
A job that needs a connected app uses the account its agent is set to use. If that agent has several accounts for the app and none of them is the default, there's nothing for the job to pick, and it won't arm — [choose one for the agent](/docs/getting-started/sharing-and-access#pick-which-account-an-agent-uses) and set it up again.
Goals [#goals]
Goals sit in the same list as your jobs, not in a section of their own. A goal is work that runs until it's *done* rather than on a clock — you describe an outcome, and the agent keeps taking runs at it until it gets there.
The difference from a job is what stops it. A scheduled job runs again because it's Tuesday; a goal runs again because it isn't finished yet. Every goal carries a success condition specific enough to check, and at the end of each attempt the agent says where it's got to — done, blocked, or carrying on — then either goes straight into the next attempt or puts it down and comes back to it later. It can't call something done while steps it set itself are still open.
There's a third, much shorter thing that looks similar: a [wait](/docs/channels/threads#when-an-agent-waits-for-something). A wait lives inside one conversation, caps out at an hour, and just pauses an agent until some condition is met. If work needs to outlive the conversation it started in, it wants a job or a goal instead.
A goal tells you once, at the end. It doesn't notify you on every attempt — you get a single notification when it finishes, and it takes you to the job rather than the thread. A goal that reached its condition arrives as **Goal completed**; one that hit a wall arrives as **Job failed**, carrying the outcome and the agent's own reasoning. Progress in the meantime is there to look at, not pushed at you.
Each goal card shows what it's chasing, where it's got to, a status, and how many attempts it's taken. There's no allowance to run down — a goal keeps going while it's getting somewhere, and stops when it's done, when the agent says it's blocked, or when several attempts in a row make no progress. Because goals and jobs share one list, the search box, the status filter and the **Mine / All** toggle all cover both, and the count above the list reads *items* rather than jobs. Running work sorts to the top either way. Jobs can be pinned; goals can't.
Stopping a goal is final in a way pausing a job isn't. Cancelling a goal's run stops the whole goal rather than that one attempt — and a goal that has finished, been blocked, or been stopped can't be started again. Describe the next push as a new goal instead.
Two ways to set one [#two-ways-to-set-one]
The Jobs page's **Create job** button makes jobs, not goals. Goals come from one of two other places, and which you pick changes how sharply the finish line gets drawn.
Say what "done" looks like in conversation, as above, and Nebula writes the success condition with you. This is the one to use when the outcome needs describing carefully — the condition it lands on is what *done* gets measured against, so it's worth getting into words.
An agent's details panel has a **Goals** card. Click **Edit**, then **Add goal**, type a one-line goal, and **Save**. Handy for standing goals that describe what an agent should keep prioritising.
A goal typed in here has no separate success condition — the line you write *is* the definition of done. If the outcome deserves a sharper test than one line can carry, set it up in conversation instead.
The **Goals** card only offers **Edit** if you have edit access to that agent. Your own Nebula orchestrator is the exception you'll meet first: its configuration is read-only, so it doesn't take goals this way. Without the button you'll still see the list, reading **No goals defined.** when it's empty.
Managing through chat [#managing-through-chat]
Most workspaces never visit the Jobs page — they just ask Nebula directly.
Pausing vs deleting [#pausing-vs-deleting]
There's a third way a job goes quiet that you didn't ask for: if the workspace runs out of
credits, the jobs that would have fired are paused instead of failing, and the workspace
owner gets an email naming the one that was skipped. These come back on their own once
anyone tops the workspace up — you don't have to hunt them down and re-enable them. See
[Workspace settings](/docs/settings/workspace#billing--credits-shared).
This is the job side of the picture. A [goal](#goals) that has already reached an
end — met, blocked, or stopped — is past resuming, so pausing and resuming applies
to it only while it's still running.
Related [#related]
# Notifications
Notifications keep you on top of what's happening in your workspace — mentions, finished tasks, jobs that ran, and more. Everything lands in your in-app inbox, and you decide which events also reach you by email, Slack, Discord, Telegram, or mobile push.
Your inbox [#your-inbox]
Open the inbox from **Notifications** in the sidebar. It sits second in the list, under Home, and carries a count of how many unread notifications you have.
Click **Notifications** in the sidebar to open them, newest first. Each one shows who it's from, what happened, and how long ago.
Click any notification to jump to the thread, conversation, or invite it points at. Opening it also marks it read.
Clear everything with **Mark all read** in the top-right. New notifications also slide in as a popup while you work — click it to open, or dismiss it with the **X**. It pauses when you hover, and settles its count into the sidebar row when it closes.
When a busy inbox buries the things you care about, filter it by type — **All**, **Mentions**, **Needs input**, **Tasks**, **Jobs**, **Other** — to focus on one kind at a time.
Need to focus? Turn on **Do Not Disturb** from the notifications page to pause the on-screen pop-ups for a set time. Your inbox and any email, Slack, or mobile delivery keep working — only the pop-up cards go quiet until the timer ends.
What you get notified about [#what-you-get-notified-about]
Your inbox always receives every event below. The descriptions match what Nebula shows when you build a rule.
| Event | When you get it |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mention** | Someone @-mentioned you in a thread |
| **Needs your input** | An agent paused awaiting your input |
| **Task completed** | An agent task finished successfully |
| **Task failed** | An agent task ran into an error |
| **Job completed** | A job ran to completion |
| **Job failed** | A job errored before completing |
| **Goal completed** | A goal reached the outcome it was set. A goal that ends any other way — blocked, or stopped making progress — arrives as **Job failed** instead |
| **Billing** | Low or depleted Nebula Credits or Tool Credits, or payment issues |
| **Workspace invite** | You were invited to a workspace |
Two of those are **transactional**, and you'll notice they aren't in the rule builder: **Billing** and **Workspace invite** always reach you, in your inbox and by email, and there's no rule to write for them. Nebula won't let you turn off the message that says your credits ran out.
One more arrives on its own: when a job can't run because a connected app's authorization has broken, Nebula sends a **Reconnect needed** alert naming the job and the app to reconnect, filed under Jobs in your inbox and pushed to your email and phone as well. It fires once when the connection breaks rather than on every failed run, and it isn't a rule you build — a job silently not running is worth interrupting you for.
Choose where notifications reach you [#choose-where-notifications-reach-you]
Go to **Settings → Notifications** to manage your destinations — *"where Nebula can reach you."* Your inbox always gets everything; destinations are for delivery *beyond* the inbox.
Every notification appears in the inbox behind the bell, with an unread dot until you open it. Always on — nothing to set up.
Delivered to your account email. Always available as a destination.
Push notifications from the browser you're reading this in, so you hear about things with Nebula in a background tab. Allow notifications when your browser asks and this browser becomes a destination — each one you sign in from is its own.
Push notifications on the Nebula mobile app. Signing in isn't enough on its own — open **Settings → Notifications** on the phone and choose **Enable**, then allow the permission your phone asks for. Each phone is its own destination. See [Push notifications](/docs/mobile/push-notifications).
Direct messages from the Nebula bot on each platform. Connect the integration first, then it becomes a destination you can deliver to.
SMS isn't available yet — only the channels above can be selected today. On the [desktop app](/docs/desktop), activity surfaces in the [Capsule](/docs/desktop/capsule) rather than as operating-system notifications.
Set up delivery rules [#set-up-delivery-rules]
A rule says "for this event, also notify me on these channels." Add as many as you like in **Settings → Notifications**.
In **Settings → Notifications**, click **Add rule**.
Pick the **event** — Mention, Task completed, Job failed, Needs you, and so on.
Under **Deliver via**, choose one or more destinations (Email, Browser, Mobile, Slack, Discord, Telegram). Leave it empty to keep that event inbox-only.
Save. The rule now shows the event and its delivery channels. Edit or delete it anytime from the same page.
Scope a rule to a channel, agent, or job [#scope-a-rule-to-a-channel-agent-or-job]
You don't have to be notified about *everything* of a kind — you can narrow a rule to a single channel, agent, or job using its **bell**.
Open the channel header, agent details, or job details and click the **bell** — it reads **Get notified** (or **Edit notifications** if a rule already exists).
Under **Notify me about**, check the events you care about for that specific entity. Each one becomes a scoped rule.
Use **Manage delivery** in the popover to jump to Settings and pick which channels those scoped notifications go to.
Sound effects [#sound-effects]
Below Do Not Disturb, a **Sounds** card controls the audio cues Nebula plays as you work. The master switch turns the lot on or off, and three toggles let you keep the ones you want.
Cues for your own actions — a message sent, a send that failed.
Cues when agents respond or need attention anywhere in the workspace.
Call cues — connecting, people joining and leaving, mute, and work being dispatched.
Sound settings are per browser rather than per account, so turning them off on your laptop won't quiet another machine you sign in on. Everything starts switched on.
Notifications are scoped to the workspace you're in — switch workspaces from the top-left dropdown to manage another one. Need a hand? Ask Nebula directly in chat, or email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
Where mentions happen — and where you'll find a bell to scope notifications per channel.
Set up the jobs whose completions and failures you can be notified about.
Turn on notifications for your phone and manage which devices get them.
Connect Slack, Discord, and Telegram so their DMs become delivery destinations.
Invite teammates — the source of workspace-invite notifications.
# Slash commands
Type `/` at the start of any message box and a list of commands opens. They do the things a sentence can't: stopping a turn, clearing context, or switching the agent into a mode. Everything else you can just ask for.
How the palette works [#how-the-palette-works]
Type `/` as the first character of an empty box. The list opens straight away and filters as you keep typing.
Pick one with the arrow keys and Enter, or click it. In the terminal, Tab completes the name without running it.
Add anything the command takes after a space — `/enhance draft a launch email`. The space closes the list, so the rest of the line is just your text.
Commands work anywhere you can type to Nebula: threads, channels, agent DMs, and the chat rail of a [live call](/docs/live). They work in the terminal too — though a call answers to a slightly different set, [below](#on-a-call).
Need a message to *start* with a literal slash — a file path, say? Type `//` and the rest goes through as ordinary text. A path in the middle of a sentence never triggers the palette anyway.
The commands you always have [#the-commands-you-always-have]
These are on every account, in every workspace, with nothing to turn on.
| Command | What it does |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `/enhance ` | Rewrites a rough request into a sharper one, shows you the result, then runs it. |
| `/plan [request]` | Turns on [plan mode](#plan-mode) — Nebula works out an approach before changing anything. |
| `/clear` | Clears the conversation's context. The thread stays; the agent starts fresh from here. |
| `/btw ` | Asks a quick side question without disturbing the work in flight. |
| `/stop` | Stops the turn in flight — whether it's running, waiting its turn, or parked on an approval card. |
| `/retry` | Runs your last failed or stopped turn again. |
| `/help [question]` | Gets you oriented, with a next step for whatever you're in the middle of. |
| `/goal ` | Sets up a [goal](/docs/jobs) — something pursued across many runs until it's done. |
| `/job ` | Turns a request into a [job](/docs/jobs) on a schedule or an app event. |
| `/tool ` | Builds a [custom toolkit](/docs/tools) for an API Nebula doesn't already cover, then puts it on an agent. |
| `/agent ` | Creates a [specialist agent](/docs/agents/custom-agents) that owns a recurring area of work. |
| `/review [focus]` | Audits the work in this conversation, read-only — several reviewers check it from different angles at once. |
Five of these need a conversation to act on. In a fresh box with no thread yet, `/clear`, `/btw`, `/stop`, `/retry` and `/review` appear greyed out with **Open a conversation first** where their description would be.
`/review` is the one command that changes which [tier](/docs/models) answers you: it runs on **Ultra** for that turn whatever you're normally on, because auditing work is exactly the kind of thing worth the extra depth. It only reads — it won't change anything it finds.
`/btw` is genuinely a side channel. The question and its answer never enter the agent's history, so the work in progress doesn't get derailed by it — but consecutive `/btw` questions do remember each other, so you can follow one up.
Plan mode [#plan-mode]
`/plan` puts the thread into a read-only mode: Nebula investigates and proposes, but doesn't change anything until you say so. It stays on across follow-up messages rather than lapsing after one turn, so you can go back and forth on the approach first.
Read-only here is enforced, not a promise. While planning, Nebula can still look around your [Computer](/docs/devices) — read files, check the git history — but the shell it gets can't write to disk, can't reach the network, and isn't handed any of your credentials. Coding harnesses stay off entirely until you approve.
Looking around this way needs the cloud Computer. On a [local device](/docs/devices/local-device) the sandbox isn't available, so Nebula plans from what it can already see rather than by exploring your machine.
When it has one, the plan arrives as a card titled **Ready to start on this plan**, with the whole thing laid out to read.
Approves it. Nebula saves the plan as a `PLAN.md` file you can refer back to, leaves plan mode, and starts work.
Send written feedback instead of approving. Plan mode stays on and Nebula revises. There's no in-place editing — you say what should change and it rewrites.
Skips the approval card for you in this workspace from now on. Plans still get made; you just stop being asked to sign off.
Nebula skips the card when there's nobody there to answer it — work running from a [job](/docs/jobs) or a trigger goes ahead on its own rather than stalling on approval that will never come.
On a call [#on-a-call]
A [live call](/docs/live) answers to its own set, because two of the commands above don't mean anything there and one extra one does.
`/enhance` and `/retry` are gone. You sharpen a request on a call by **talking** — that's what the medium is for — and "run the last failed turn again" has no single referent when several pieces of work are in flight at once.
Everything else carries over, and `/thread` joins them.
`/thread ` starts a piece of work from the call without saying it out loud. Nebula takes the opening clause of what you typed as the thread's title, so it's recognisable in the call's work list afterwards.
Type a slug the call doesn't recognise and nothing is dispatched blind — it's treated as ordinary speech, so a typo can't quietly mint a work thread. A slug that names a real workspace skill still works, because it reaches the agent as a normal request.
Your skills are commands too [#your-skills-are-commands-too]
Beyond the fixed list, the palette fills up from [skills](/docs/agents/skills) — the ones the answering agent can reach, and the ones belonging to any other agent you're able to address. Connecting an app adds the commands that come with it too, so the list on a research agent looks different from the list on one wired into your repo.
That's why this page doesn't try to enumerate them. Open the palette and the list you see is the true one.
A command can answer from another agent [#a-command-can-answer-from-another-agent]
If a skill belongs to a different agent, running its command hands that turn to the agent that owns it — you don't have to go and find it first. Nebula routes the work and that agent answers, then you carry on where you were.
You only see commands from agents you could address anyway, so a teammate's own Nebula orchestrator never shows up in your palette. And a skill someone writes can never take over a built-in name — naming a skill `review` doesn't change what `/review` does for anyone.
The palette shows a workable set rather than an exhaustive one. If you remember a skill's name and it isn't listed, type it anyway — it still runs.
See a `/command` in a message and not know what it does? Click it. Nebula explains it in place rather than running it.
Related [#related]
# Support
The fastest way to get help is to ask Nebula. Your agent has tools to interact with the system directly — it can create channels, modify agents, check your billing, and troubleshoot most issues on the spot.
Ask Nebula first [#ask-nebula-first]
Nebula can handle most support questions without you leaving the chat. Try asking things like:
Nebula can also help you compose detailed support emails when you need to reach the team:
Contact the team [#contact-the-team]
For bug reports, feature requests, or anything Nebula can't resolve directly:
* **Email:** [support@nebula.gg](mailto:support@nebula.gg)
* **Response time:** Typically within 24 hours on business days
When writing to support, include:
* What you were trying to do
* What happened instead
* Your workspace ID (ask Nebula if you're not sure)
Common issues, fast paths [#common-issues-fast-paths]
A handful of questions come up often. Each has a "ask Nebula" path and a docs page in case you want the full picture.
Sign out and back in from your profile menu. If the issue persists, clear cookies for `nebula.gg`. Still stuck? Email [support@nebula.gg](mailto:support@nebula.gg) with the device and browser you're using.
Open the agent's details panel and check its **Instructions** and **Tools**. Edit the instructions to be more specific, or ask Nebula to revise them for you. See [Configure an agent](/docs/agents/configure).
Open the job from the Jobs page and check **Activity** for the last run. Most misses are caused by paused triggers, missing variables, or auth expiry on a connected app. See [Jobs](/docs/jobs).
Open **Settings → Accounts**, find the app — personal connections and shared workspace bots are rows in the same list — and reconnect it. Re-authorize in the popup. Most "agent stopped working" reports trace to expired tokens.
Open **Workspace Settings → Billing** to see both totals. Which one is empty tells you what stopped: out of **Nebula Credits** and chat on Nebula models, basic tools, and cloud-device work stop; out of **Tool Credits** and only third-party models, media generation, and browsing stop. The two don't substitute for each other, so topping up the wrong one won't unblock you. The workspace owner or an admin can top up either and set a separate auto top-up for each. See [Workspace settings](/docs/settings/workspace#billing--credits-shared).
It doesn't get thrown away. Your agent keeps going with whatever tools still work, stops retrying the ones it can't use, and finishes what it can — then tells you plainly what it completed and what's blocked.
A card appears in the conversation naming the work that stopped, with a button to top up. It clears itself once the right balance is funded, so you don't have to dismiss it. A **Tool Credits** block offers a top-up and nothing else, because a top-up is the only thing that clears that one.
Jobs that get skipped for credits are paused rather than deleted, and the workspace owner gets an email saying which one was skipped. Once anyone tops the workspace up, they switch themselves back on — there's nothing to re-enable by hand. See [Jobs](/docs/jobs).
Browse the docs [#browse-the-docs]
Want to know what shipped recently? Every update lands on the [changelog](https://nebula.gg/changelog), which you can also follow by [RSS](https://nebula.gg/api/changelog/rss). Signed in, the same entries show up as **What's new** in the account menu at the bottom of the sidebar, and Nebula pops a summary the first time you come back after a release. Entries that only affect one place are badged **mobile**, **desktop**, or **cli**, so you can tell what applies to you.
# What agents can do
Agents in your workspace come with built-in tools — web search, code, browsing, and media — that expand automatically when you connect apps. To shape *how* an agent uses those tools, give it reusable [skills](/docs/agents/skills).
Built-in tools [#built-in-tools]
Searches the web for current information, articles, and data.
Runs Python, Bash, or TypeScript on the workspace [Computer](/docs/devices). Common data science libraries (pandas, numpy, matplotlib) are pre-installed.
Reads and extracts structured data from web pages.
Controls a real browser to interact with websites — click, fill forms, navigate, extract.
Generates and processes images, audio, and video; transcribes recordings.
Sends email and posts messages on connected platforms (Slack, Discord, Telegram, etc.).
Pauses on a condition — a build finishing, a file arriving — and picks the thread back up once it's met, without holding up the conversation. See [when an agent waits](/docs/channels/threads#when-an-agent-waits-for-something).
App integrations [#app-integrations]
When you [connect an app](/docs/tools) to your workspace, Nebula adds that app's tools to the relevant agents automatically. Browse the full catalog of what's available:
Tools in action [#tools-in-action]
Permissions [#permissions]
Permissions decide what an agent is allowed to do. There are two paths in:
When you [connect an app](/docs/tools) via OAuth, the provider shows a consent screen listing exactly what Nebula is asking for — read inbox, send mail, list repos, etc. Nebula never gets more than you approve.
Open **Settings → Accounts**, find the connection, and open it to see the full scope list.
Disconnect the app from the same panel. You can reconnect any time.
Revoke access at the provider (Google account, GitHub settings, etc.), then reconnect — the consent screen reappears.
For tools that use an API key or token, permissions are whatever **the key** can do. A GitHub token scoped to `read:repo` only gives Nebula read access. To narrow what an agent can do, generate a scoped key in that service before pasting it into Nebula.
Nebula stores credentials encrypted. Never paste a key into a chat message — use the variable form in the agent details panel.
Best practice: grant only what the agent needs. Read-only access is plenty for monitoring; only grant write access when the agent is supposed to act.
Permissions decide what an agent *can* reach. For a second check at the moment an agent acts, turn on the [safety gate](/docs/settings/approvals) — it pauses risky writes and deletes for your approval.
Related [#related]
# Configure an agent
Every agent has its own configuration page where you can edit how it behaves, what it can do, and what it remembers. Open **Agents** from the sidebar and click the agent.
Visibility (**private** vs **workspace**) controls who can use an agent — and a shared agent acts through **your** connected apps. See [Agent scoping & access](/docs/getting-started/sharing-and-access).
Finding your way around [#finding-your-way-around]
The page opens on the agent's identity, with everything else split across four tabs.
Description, instructions, visibility, and the model this agent runs on.
The toolkits it can call, its custom tools, and the connected accounts and variables they need.
Scheduled and event-driven work attached to this agent, plus its goals.
Skills and memory — the standing knowledge it carries between conversations.
While you're in a conversation, the same settings are a click away: open the details panel from the header without leaving the thread.
Name and description [#name-and-description]
The name helps Nebula decide when to hand work to this agent — keep it descriptive. The short description appears in mentions, and Nebula uses it when choosing between the agents on its [roster](/docs/agents/roster).
Visibility [#visibility]
Each agent in a workspace is either:
Model [#model]
The details panel has a **Model** row. Open it and you get the same three [Nebula tiers](/docs/models#nebula-tiers) you'd pick from the composer — **Flash**, **Max** and **Ultra** — with **Default** above them and **All models** below for pinning a specific model from any provider. Whatever you pick applies immediately.
**Default** is where to leave it unless you have a reason not to. On Default the agent follows [the workspace default](/docs/models#where-your-choice-lands), so an owner or admin changing that one setting moves every agent nobody has pinned. Pin a tier instead when the agent's work has a consistent shape — a deeper tier for one that reviews code, a fast one for an agent that files and tags.
An agent's model is what it uses wherever nothing more specific applies. A model [pinned to a thread](/docs/models) wins inside that thread, so a conversation you've deliberately moved to a heavier tier stays there even when a differently-configured agent picks it up.
Changing it needs edit access on the agent. Without that, the row still tells you what the agent runs on — it just isn't a control.
Instructions (system prompt) [#instructions-system-prompt]
Instructions define the agent's role, voice, and rules. They're sent with every message.
Click **Edit** next to **Instructions** in the details panel, or ask Nebula to update them in chat.
```text
## Role
You are [role]. You specialize in [domain].
## Behavior
- [Communication style]
- [Response format]
- [How to handle uncertainty]
## Rules
- [Always do this]
- [Never do this]
- [Scope boundaries]
## Context
[Standing facts: company, product, audience, terminology]
```
**Too vague.** "You are a helpful assistant" is empty. Be specific about domain and audience.
**Too long.** Reference material belongs in [Skills](/docs/agents/skills) or a memory, not instructions.
**Contradictory.** Don't say "be concise" and "provide detailed analysis" in the same prompt.
**Capability lists.** You don't need to tell the agent what tools it has — Nebula handles that.
Run 5–10 representative requests, note where the agent drifts, add a sentence to address it, repeat. Most prompts don't land on the first draft.
Memory [#memory]
Agents remember useful facts across conversations — preferences, resource mappings, project context — so you don't repeat yourself. Memory is separate from any single conversation's history.
There are two kinds, and the difference is when they're in play. Most of what an agent learns is **recalled** — kept aside and pulled in when it's relevant to what you're doing. A smaller set is **saved** — carried into every single run, whether or not it looks relevant. Ask an agent to *remember* something and you get the second kind; that's the phrasing that pins a fact permanently, so keep it for standing instructions rather than passing detail.
After an agent completes a task with tool calls, Nebula extracts useful facts in the background. You don't have to do anything.
Just ask:
Pin a memory to one channel so it doesn't leak elsewhere:
Forgetting or correcting works the same way — ask the agent to update or forget it. You can also see everything it has picked up under **Settings → Memories**, grouped by app: open a memory to see where it came from and whether the agent learned it on its own or you told it, delete one, or clear out anything that's gone stale. Changing what a memory *says* is a conversation, not a form — ask the agent and it rewrites it.
Tools [#tools]
Tools are the things the agent can actually do — web search, code, browsing, app actions. The agent's **Tools** tab lists the ones it has, each with what it does and which account it uses. An agent with none yet reads **No tools connected**.
Select **Connect a tool** and pick an integration from the searchable list. If it needs an account, connect that under [Settings → Accounts](/docs/settings/connections), then choose it for this agent in the **Accounts** section below — giving an agent a tool, authorizing the app, and picking which account it runs as are three separate steps.
Select the trash icon on the tool, then confirm. Nebula tells you what it's about to do: the tool stops being available to *this* agent, and **your connected account is not deleted** — other agents using it are unaffected, and you can add it back later.
Built-in tools that every agent gets aren't listed here, so there's nothing to remove for those. If you don't have edit access to the agent, the remove control is visible but disabled and says so.
Your own Nebula orchestrator is a special case: you can add and remove its tools even though its model, device, and instructions stay fixed.
See [Agent tools](/docs/agents/capabilities) for the full catalog and what each tool does.
Accounts and variables [#accounts-and-variables]
Third-party connections this agent uses (Slack, GitHub, Gmail). A green check means active. Each app here needs an account **chosen for this agent** — one that reads **Choose account** hasn't got one yet, and the agent will ask when it first needs that app. Open the picker to select from your connected accounts, or **Connect new account** to add one. You can pick more than one, which is what you want when you've connected the same app twice (two Slack workspaces, say).
Secrets and config values some tools require — API keys, tokens. Status badges show **Set** (ready) or **Missing** (action needed). Always set them through the form in the panel; never paste a secret into a chat message.
Triggers [#triggers]
Any [automations](/docs/jobs) attached to this agent appear here with their schedule or event type. Click one to edit, hover and click **×** to remove.
Deleting an agent [#deleting-an-agent]
Click **Delete**, then confirm. This is permanent: it removes the agent and its DM channel, and any jobs scheduled by it stop running. The agent also drops off every roster it was on.
Deleting is not the same as removing an agent from your [roster](/docs/agents/roster). Removing it just stops Nebula delegating to it — the agent, its jobs, and its history all survive.
Platform agents (marked with a **Platform** badge) and your own Nebula orchestrator can't be deleted.
Related [#related]
# Create a custom agent
You can create custom agents in Nebula to handle specific tasks, workflows, or app integrations — built from the Agents page or just by describing what you want in chat.
How to create an agent [#how-to-create-an-agent]
Open **Agents** from the sidebar and click **Create agent** to open the Create Agent wizard, then step through five short pages.
**Identity**
— name the agent (e.g. "PR Reviewer" or "News Monitor"), and optionally add an image and pick a model. The workspace default model is usually right.
**Description**
— write what the agent handles, its personality, and the outcomes you want. For example: "A research assistant that summarizes articles and cites sources."
**Tools**
— pick the toolkits and services it can act on, like Slack, GitHub, or web search. You can change these later.
**Access**
— set who can use it: general workspace access (none, read, or write), specific people, and the device it runs on (Automatic for cloud, or a pinned one). See
[scoping & access](/docs/getting-started/sharing-and-access)
.
**Review & create**
— check the summary, jump back to edit anything, then click
**Create agent**
. The new agent appears on your Agents page immediately.
Describe what you need directly in any conversation:
Nebula will create the agent, configure its tools, and connect it to the right apps — walking you through any setup steps needed.
After creating an agent [#after-creating-an-agent]
Your agent lands ready to work — name, description, model, tools, and access all set. Create it in chat and Nebula fills in the tools and instructions from your description; use the wizard and you choose them as you go. Fine-tune any of it later from the [agent details panel](/docs/agents/configure).
Appears on the
**Agents**
page — click to open and configure it.
Joins your
[roster](/docs/agents/roster)
automatically, so Nebula can hand it work.
Can be invoked directly by mentioning it in chat.
Can be linked to
[automated triggers](/docs/jobs)
.
Configuring your agent [#configuring-your-agent]
After creating an agent, open its details panel to fine-tune model, instructions, goals, tools, accounts, and variables. See [Configure & Manage Agents](/docs/agents/configure) for the complete guide.
What's next? [#whats-next]
# Agents in Nebula
Agents are the AI workers in your workspace. When you ask Nebula to do something, it acts as a coordinator — bringing in the specialists on its [roster](/docs/agents/roster) and handing work to them. Agents are shared with everyone in the workspace by default.
Agents are **private** to you or shared with your whole **workspace**. A shared agent runs with **its owner's** connected apps. See [Agent scoping & access](/docs/getting-started/sharing-and-access).
Where agents come from [#where-agents-come-from]
A new workspace starts as a blank slate: you get your own Nebula and nothing else. Agents arrive as the work calls for them.
Describe what you want and Nebula builds the agent, picks its tools, and adds it to your workspace.
Click **Create agent** on the Agents page and step through identity, tools, and access yourself.
Any agent a teammate makes workspace-visible shows up under **All workspace agents**, ready for you to use or add to your roster.
Your own Nebula [#your-own-nebula]
Every member of a workspace gets their **own** Nebula orchestrator — the coordinator you talk to. It's yours: make it yours.
By default it's "Nebula" with the standard avatar, but you can rename your orchestrator and give it a custom icon from **Settings → Agents**.
Teammates can open your orchestrator to see how it's set up — its model, tools, and brain — but they can't send it messages. Each person talks only to their own.
Your orchestrator sits at the top of the **Agents** page as the root of your [roster](/docs/agents/roster), with everything it can hand work to branching beneath it. Teammates' orchestrators aren't listed there at all — a clear line between the Nebula you drive and the ones you can only look at.
Workspace-scoped, with optional privacy [#workspace-scoped-with-optional-privacy]
Every agent lives in a workspace. By default, agents are visible to everyone in that workspace — on the Agents page, in mentions, and in automations. You can set an agent to **Private** if it should only be yours.
You can use a private agent in a **shared channel** — it isn't confined to your own DMs. To everyone else in that channel it simply isn't there: it won't appear in the agent list, won't come up as somewhere to hand work, and won't resolve if they try to mention it. See [Sharing & access](/docs/getting-started/sharing-and-access).
Not sure how to configure an agent? Ask Nebula — it can build, edit, and rename agents directly in chat.
How agents get work done [#how-agents-get-work-done]
Reads context — the current thread, attached files, connected app data.
Calls the tools it needs — search, code, the browser, app actions — on the workspace Computer.
Reports results back to Nebula, which summarizes them in the thread.
For longer tasks, watch the agent's progress live in the thread view. Other workspace members can watch too — agents are shared work.
Related [#related]
# Agent roster
Your **roster** is the set of agents your Nebula orchestrator is allowed to hand work to. You curate it from the **Agents** page, and Nebula delegates only to what's on it.
What the roster controls [#what-the-roster-controls]
The roster governs the work Nebula hands off *on its own initiative*. When it decides a request is better handled by a specialist, it can only reach for an agent you've put on the list.
Mentioning an agent always works. A roster keeps Nebula's *own* choices tight; it never blocks you from calling an agent by name.
An empty roster means Nebula delegates to nobody. It'll handle what it can with its own tools and ask you to add someone for the rest.
What's on your roster already [#whats-on-your-roster-already]
Every agent you create joins your roster automatically — from the wizard or from chat. There's nothing extra to do after building one.
Agents you owned before the roster shipped were added for you, so delegation you relied on kept working.
An agent a teammate shared with the workspace is **not** on your roster until you add it. It's visible on the Agents page and you can still mention it — Nebula just won't pick it unprompted.
Adding an agent [#adding-an-agent]
Open
**Agents**
from the sidebar. Your orchestrator sits at the top under
**Agent Roster**
, with its roster branching beneath it.
Scroll to
**All workspace agents**
— everything you can reach that isn't already on the list.
Click
**Add to roster**
on the agent you want. It moves up into the tree straight away.
Removing an agent [#removing-an-agent]
Hover the agent's card in the roster tree and click the
**×**
in its corner.
Confirm
**Remove**
. Nebula stops delegating to it and the agent drops back into
**All workspace agents**
.
Removing from a roster never deletes the agent. Its configuration, jobs, and history are untouched, and anyone else who has it on *their* roster is unaffected.
Everyone curates their own [#everyone-curates-their-own]
A roster belongs to one person's orchestrator in one workspace. You and a teammate can share every agent in the workspace and still have completely different rosters — and neither of you can edit the other's.
Good to know [#good-to-know]
Most-delegated-first. The agents Nebula actually leans on rise to the top, so the list reflects how you work rather than the order you added things.
No. Add as many agents as are genuinely useful — though a tighter roster gives Nebula a clearer choice.
No. Every member has their own Nebula, and pointing one at another would route work in a circle. Only regular agents can be added.
It drops off automatically. There's nothing to clean up.
Not yet — the roster is edited on the **Agents** page. Nebula *will* tell you when it wanted an agent that wasn't available and ask whether to add it, but you make the change yourself.
Related [#related]
# Skills
Skills are reusable instructions you teach Nebula once and reuse forever. Write up how you want a task done — your invoice format, your code-review checklist, your brand voice — save it as a skill, and any agent can follow it on demand instead of you re-explaining every time.
Every skill in your workspace also turns up as a [slash command](/docs/slash-commands) — type `/` in any message box and it's there by name, alongside the built-in ones.
What a skill is [#what-a-skill-is]
A skill is a single Markdown file (a `SKILL.md`) with a name and a set of instructions. It lives in your workspace's **brain** alongside memories, and agents pull it in when it's relevant to the task at hand. You manage skills from **Settings → Skills** (under **Workspace brain**).
Capture a procedure once. Every future request that needs it follows the same steps, the same way.
Skills you add are available to everyone in the workspace — a shared playbook your whole team's agents can draw on.
Scope: Nebula or a specific agent [#scope-nebula-or-a-specific-agent]
When you add a skill, you choose who it belongs to. A scope badge on each skill card shows which it is.
Attach the skill to Nebula itself so it applies broadly — whenever Nebula coordinates work that fits, the skill is in play.
Attach it to one agent — your code agent, your research agent — so the instructions only apply when that agent is doing the work.
Adding a skill [#adding-a-skill]
There are three ways to add one, all from the **All skills** tab.
Pick a scope (Nebula or an agent), then upload a `SKILL.md` file with your instructions. This is the route when you've written the skill yourself.
Paste a direct link to a `SKILL.md` — a GitHub raw link, say. Nebula safety-scans it before installing, then asks whether to attach it to Nebula or a specific agent.
Open the **Registry** tab and search the **ClawHub** skill registry by what you want to do — *"pdf generation"*, *"code review"* — then install a match to Nebula or an agent.
Using a skill in chat [#using-a-skill-in-chat]
Reference any skill with **`@skill:name`** in a thread to point an agent at it directly:
```text
@skill:invoice-parser pull the line items out of this PDF and total them
```
You usually don't have to — agents reach for a relevant skill on their own — but calling it by name guarantees the instructions are applied for that request.
Where a skill came from [#where-a-skill-came-from]
Each skill card carries an **origin badge** so you can tell at a glance how it got into your workspace.
| Badge | Meaning |
| ----------------- | ----------------------------------- |
| **Authored** | You wrote it directly in Nebula |
| **Uploaded** | You uploaded a `SKILL.md` file |
| **From URL** | Installed from a remote link |
| **From registry** | Installed from the ClawHub registry |
Not sure how to write a skill? Ask Nebula in chat — describe the procedure and it can draft the `SKILL.md` for you. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# Channels
A channel is a room in your workspace dedicated to a topic — a project, an event, a team. You and your teammates work in it together, with agents you've added.
Channels vs DMs [#channels-vs-dms]
Creating a channel [#creating-a-channel]
Open the command palette with **⌘K** and choose **Create channel** — or just ask Nebula in chat (below).
Give it a name. Nebula slugs it for you (so "Grad Party" becomes ).
Pick visibility — **Workspace** so everyone in the workspace can find and join it, or **Private** so only the people you add can see it. Private (locked) channels show a lock icon.
Add the agents you want available in the channel. You can change this later.
Channel members [#channel-members]
Any workspace admin can add or remove members on a channel. Members can post, reply, mention agents, and start new threads.
Mention an agent in a channel to bring it in mid-conversation, e.g. " can you summarize this?" Even if the agent isn't in the channel yet, mentioning it will pull it in.
The agent list isn't a gate [#the-agent-list-isnt-a-gate]
The agents shown on a channel record who has taken part, not who is allowed to. It's a guest list after the fact, not a bouncer — so adding an agent doesn't reserve replies for it, and leaving one off doesn't keep it out.
If you want to limit which agents Nebula reaches for on its own, that's the [agent roster](/docs/agents/roster) — a per-person list, not a per-channel one.
Create and manage in chat [#create-and-manage-in-chat]
You don't have to leave the conversation to add or change a channel.
Sharing files [#sharing-files]
Drop a file into a channel and every member — and every agent in the channel — can read it. Files attached to a thread stay scoped to that thread; files dropped at the channel level are available everywhere in it.
Related [#related]
# Threads
A thread is a single conversation inside a channel. Every channel can hold many threads — one per topic, request, or working session — and Nebula writes a short summary at the top of each so you can pick up where you left off.
A thread you haven't caught up on carries an amber dot and a bolder title, so it stands out without the row changing colour. Threads you're part of also carry a small **Mine** badge, so you can pick them out without filtering the rest away.
Why threads [#why-threads]
Threads keep work organized and keep agents focused. Each thread has its own context, so agents don't drag yesterday's discussion into today's request — and you can scan a channel and instantly see what's been happening.
Keeps the conversation tight. New question? New thread.
Nebula writes a short blurb so anyone joining late knows what's going on.
Agents respond based on the current thread, not the whole channel.
Files dropped into a thread stay there. Agents only see what's in the room.
Starting a thread [#starting-a-thread]
Open a channel. Its threads are listed down the page, newest activity first.
Type your first message into the composer at the **top** of that list — it reads *Start a thread in #channel-name*, and it always opens a new thread rather than adding to one.
Send it. Nebula generates the thread's title and summary from your message, refining both as the conversation grows.
Renaming a thread [#renaming-a-thread]
Nebula titles each thread automatically, but you can set your own. Open **Thread details** from the icon in the conversation's top-right corner, hover the title and click the **pencil**, type a new name, and press **Enter** (or **Escape** to cancel).
A title you set is pinned — it sticks in thread lists and the sidebar, and Nebula stops auto-renaming the thread. To hand the title back to Nebula, rename the thread and clear the field: it reverts to the latest auto-generated summary title and resumes updating on its own.
DM and job threads take their names from the agent or trigger they belong to, so those aren't renamable.
Managing a thread by asking [#managing-a-thread-by-asking]
You don't have to reach for the menus. Ask Nebula inside a thread and it can tidy the thread up for you.
| Ask for | What happens |
| ----------------------- | ------------------------------------------ |
| **Rename** | Sets the title, same as editing it by hand |
| **Pin / unpin** | Holds the thread at the top of your list |
| **Tag / untag** | Attaches a `#tag`, creating it if it's new |
| **Share / unshare** | Turns public sharing on or off |
| **Archive / unarchive** | Files it away, reversibly |
| **Delete** | Removes the thread |
A few limits are worth knowing. Nebula acts on **the thread you're in** — it won't reach across into another one, so go there and ask again. Sharing is limited to whoever started the thread, and private one-to-one conversations like DMs can't be shared at all. Agent DMs, job runs, and miniapp threads can't be archived, since they belong to the thing that created them. And a thread has to come out of the archive before it can be deleted.
"Context cleared" [#context-cleared]
When you open a brand-new thread, you'll see a small **Context cleared** marker. That's Nebula confirming the agent isn't carrying over anything from the previous thread — fresh slate, fresh response.
If you want to clear context inside a long-running thread (say, switch topics mid-conversation), type `/clear` and Nebula resets just that thread's working memory. Files, summary, and history stay — only the agent's short-term context resets.
Replying & mentioning [#replying--mentioning]
Anyone in the channel can reply in a thread. Type **`@`** to mention, or **`#`** to point at a channel. The `@` picker is grouped into tabs — **Agents**, **Jobs**, **Mini apps**, **Devices** — so you can reach more than just people.
Only agents and teammates are *addressed* by a mention. The other three are links: they give you and the agent a clickable reference to the thing, and they don't start anything on their own.
Pull in an agent or teammate who isn't already watching — e.g. or . Mentioning an agent that isn't in the channel brings it in, and it's the one thing that always reaches the agent you named.
Reference one of your [jobs](/docs/jobs), like , to point the conversation at it. It links to the job — it doesn't run it.
Reference a [mini app](/docs/miniapps/using), like , so anyone reading can open it in one click.
Reference a [device](/docs/devices), like , when you're talking about a specific machine.
Link another channel so people can jump straight to it.
Point an agent at a specific file already in the conversation — see [Files](/docs/files). Files aren't in the `@` picker; you reference one that's already in the thread.
Jobs, mini apps, and devices need their prefix to resolve — pick them from the picker rather than typing a bare name, which Nebula only ever reads as an agent, a person, or a job.
Stuck? Ask Nebula directly inside the thread — it can do things like rename the thread, invite an agent, or summarize the conversation for you.
Reacting to messages [#reacting-to-messages]
Hover any message and a small toolbar floats in just above it, carrying three quick emoji — 👍 👎 ❤️ — plus an **Add reaction** button for the rest of the set. Click one to react; click it again to take it back. Reactions show up as a pill under the message with a running count — a fast way to ack a result or vote without adding a reply.
Nine to choose from — 👍 👎 ❤️ 👀 🎉 😂 🤔 🙏 🔥 — and it's one shared set across web and mobile, so the picker looks the same everywhere and counts always line up.
Agent replies are always reactable — thumbs-up the answer you want to keep. You can't react to your own messages.
Who's here [#whos-here]
Threads show you who else is in the room in real time, so collaboration feels live instead of after-the-fact.
Avatars show who's participating, with a green dot on anyone viewing the thread right now. Agents appear with their bot avatars; people with their profile pictures.
While an agent is mid-reply you get a single line at the bottom of the thread — pulsing dots, what it's doing, how long it's been at it, and a **Stop** button. That's the only activity signal, so there's nothing else to keep an eye on.
Scrolling up while an agent works no longer yanks you back down — the thread only follows the bottom when you're already there.
Sending, queueing & steering [#sending-queueing--steering]
How you send a message depends on whether an agent is already working.
So you never have to wait for an agent to finish before lining up your next message — type it and hit **Enter** to queue it, or **⌘/Ctrl + Enter** to steer the agent that's running right now. A queued message sits below the input reading *"Queued — runs after the current reply"* with two buttons: **Send now** drops it into the running turn immediately instead of waiting, and **Cancel** pulls it back out of the queue.
When an agent waits for something [#when-an-agent-waits-for-something]
Sometimes an agent can't finish until something else happens — a build goes green, a review lands, a file shows up, or it simply needs to give something a couple of minutes. Rather than sit there burning the turn, it sets the condition aside and picks the thread back up when the condition is met.
You'll see this as a strip along the top of the composer. Collapsed, it reads **Running** or **Waiting** followed by what's being worked on and how long is left, or **{`{n}`} background tasks** when there's more than one; expand it to see each, with **Checking periodically** on the ones being re-checked and **Working in the background** on work that's genuinely running.
**Cancel** on any row calls it off, including a coding session the agent has left running in the background — that used to be un-stoppable from here and is now just another row. If the task isn't yours the button is there but greyed, and hovering it tells you only its owner can cancel it.
The thread stays yours throughout. Typing still works, and the agent can carry on with anything that doesn't depend on the answer. When a wait finishes, the transcript gets one line saying how it went — resolved, timed out, or cancelled — and the agent continues from there.
Waits are for short pauses inside work already in progress, so they cap out at an hour. For anything longer, hand it to a [job or a goal](/docs/jobs): a goal if there's a finish line to work towards across several attempts, a scheduled job if you want something watched indefinitely with no particular end.
Following an agent's work [#following-an-agents-work]
While an agent works, the thread shows a live **Thinking** indicator — a status line with a running timer, and, once the model starts reasoning, a short summary of what it's working through plus a token count. The individual tool steps show separately in the activity log below the reply, not on that line.
Click **View activity** on any reply to open the activity log — the prompt that kicked it off, every agent that pitched in, and the full run of tool calls and messages. Past turns show a count like *"3 tool calls, 2 messages"*; click to expand.
When an agent searches the web, its answer carries numbered citation chips and a **Sources** footer. Click any source to open it in a new tab.
The log opens as a panel beside the conversation, and splits one reply into four views:
The run itself, in order — your original message, each agent's tool calls and working notes, and a **Changes** section at the end listing anything created, updated or deleted along the way — files, jobs, agents, memories, variables, miniapps and skills, each row naming what it was and what happened to it. While it's still going you get a **Working** line with a **Cancel** button; when it's done that becomes **Done**.
Every file the run touched, with a count on the tab so you can see there's something there without opening it. Click any file to preview it in place.
The commands the agent ran, accumulated as it goes, if the work involved a [device](/docs/devices).
A live view of the browser session when an agent is browsing for you, so you can watch rather than guess.
Terminal and Browser carry a small dot until you've looked at them, so you can tell whether the agent did anything there.
The machine and folder a thread works in [#the-machine-and-folder-a-thread-works-in]
A thread remembers both the [device](/docs/devices) it runs on and, once something puts it in a particular folder — a repo it's checked out, a project directory — where that work happens. Two small badges in the composer, beside the model picker, tell you which is which.
Names the machine this thread runs on, with an icon that distinguishes your own computer from a cloud device. Select it to open that device. The tooltip spells it out — *Runs on your machine "…"* or *Runs on the cloud device "…"*.
Shows the last couple of segments of the path in monospace. Select it to open that device's file browser at exactly that folder. It only appears once a real folder is attached — a thread sitting in the device's home folder doesn't need a badge to say so.
**Thread details** spells out the full **Working directory** whenever one is set.
That pairing sticks for the whole thread. Every command the agent runs afterwards and every relative file path it mentions resolves from there, so it doesn't have to find its way back each time. The folder is tied to the machine, so if a run lands on a different device it starts from that device's home folder instead — your folder isn't lost, and the thread re-attaches to it next time it's back on the right machine.
In the browser and the desktop app these badges are a read-out, not a control — the agent moves the thread as the work leads it somewhere, and you can just ask it to work elsewhere. The [CLI](/docs/cli) is the exception: it pins the thread to the machine and folder you launched it from, after asking you first.
On a shared thread, teammates don't necessarily see what you see. Your own computer is never addressable by anyone else, so a teammate reads their own device on the badge instead of yours — and if they can't reach the machine your folder lives on, they don't see the folder at all. It's a privacy boundary, not a bug.
Jumping around with chapters [#jumping-around-with-chapters]
Long threads get an automatic outline. As the conversation builds, Nebula groups it into **chapters** — titled sections you can scan and jump between, like a table of contents for the thread.
Look to the right of the conversation for the chapters rail. It sits collapsed as thin markers and expands on hover into a numbered list of titles.
Click any chapter to jump straight to that point in the thread — the message flashes so you can spot it. A **live** badge marks a chapter Nebula is still writing.
Hover a chapter and click the **link** icon to copy a share link that opens the thread at exactly that spot — handy for pointing a teammate at one decision instead of the whole thread.
Pin the panel open with the **pin** icon if you want it to stay expanded while you read, or hit **refresh** to re-pull the outline.
Related [#related]
# Calls from the terminal
You can take a [live call](/docs/live) entirely from the terminal — start one, join one already running, or send a message into it without opening the room. The CLI joins **chat-first**: you're connected and reading, but not broadcasting, until you say so.
Starting a call [#starting-a-call]
`nebula-ai call start` opens a new session and tells you the two things you need next: the call's **thread ID**, and the exact command to open it.
Add `--title` to name it, `--private` to keep it to you and whoever you invite, or `--thread` to seed it from an existing conversation so the agents arrive with that context.
`--thread` on `start` and the thread ID everywhere else are different things. On `start` it's an option naming the conversation an agent should *read for context*. On every other `call` command it's the required first argument naming *which call you mean*.
Hold on to that ID — every other `call` command takes it. If you've lost it, `nebula-ai channels list` lists your conversations with an **ID** column.
Joining and checking [#joining-and-checking]
`nebula-ai call join ` drops you into a call that's already running.
`nebula-ai call list ` shows that conversation's calls, live ones first; `nebula-ai call status ` reports on one you're in.
`nebula-ai call leave ` takes you out. `nebula-ai call end ` ends it for everyone, so reach for that one deliberately.
Talking without joining [#talking-without-joining]
`nebula-ai call chat ` sends a message into a call and returns — useful from a script, or when you just want to answer a question without putting on a headset.
It reads standard input when you leave `-m` off, so you can pipe into it — `tail -f build.log | nebula-ai call chat thr_8f2a1c` reads the pipe once, to the end, rather than flooding the call line by line.
Voice is a two-step opt-in [#voice-is-a-two-step-opt-in]
Because the CLI joins muted and data-only, getting your voice into the room takes two keys, in this order.
Press v to enter listening mode. The chip beside the call's title moves from `✎ chat` to `◎ listening`, and call audio starts playing.
Press m to unmute your microphone. The chip becomes `● voice` and the room can hear you.
The chip is always the honest answer to "can anyone hear me?" — `✎ chat` and `◎ listening` both mean your mic is off. `● cam` means your camera is on as well.
Reading the room [#reading-the-room]
Everyone on the call gets a glyph, so you can follow along without audio at all. Agents get the fuller vocabulary, because there's more to say about what an agent is doing.
| Glyph | Meaning |
| ----- | ----------------------- |
| `◉` | Speaking now |
| `◎` | Connected and listening |
| `○` | Disconnected |
Agents add three more — `◐` working (running a tool), `◍` thinking, and `◌` in the background (working, but not speaking) — plus a written state beside the name and an `[active]` or `[background]` posture. p switches an agent between the two. People show a glyph and a name only.
Keys inside a call [#keys-inside-a-call]
| Key | What it does |
| --------------------------- | ---------------------------------------------- |
| i | Type a message |
| v | Enter or leave voice |
| m | Mute or unmute your mic |
| o | Toggle the agent's audio |
| c | Camera on or off |
| p | Switch the agent between active and background |
| r / w | Recap / dispatched work |
| R | Reconnect |
| ^P | Hang up |
| E | End the call for everyone |
| Esc | Back |
Running without a screen [#running-without-a-screen]
`--headless` runs the audio engine with no interface at all, which is what you want on a server or in a container.
It's a machine interface rather than a readable one: instead of printing a confirmation and returning, it streams one JSON object per line to standard output and stays in the foreground until the call ends.
Pair it with `--chat` to join data-only with no audio, or `--muted` to connect audio but never publish your microphone. Because it holds the terminal, run it under whatever keeps long-lived processes alive on that box.
Before you rely on it [#before-you-rely-on-it]
Voice needs a working audio backend, and **the camera needs `ffmpeg` on your `PATH`**. Rather than finding out mid-call, ask the CLI what this machine can actually do.
Every line under **Vision** and **Audio** reads `available`, `gated` or `unsupported` — `gated` means the machine could do it but something's in the way, and the note in parentheses says what. The **Call** block is different: it doesn't grade anything, it shows the mode the engine would pick and the exact commands it would run to reach your mic and speaker. That's the block to read when audio works elsewhere but not here.
Camera sits under **Vision**, not **Call** — a call uses it, but it's the machine's capability, and `nebula-ai capabilities` groups by what the machine has rather than by what wants it.
A call still costs [Nebula Credits](/docs/settings/workspace) per active minute whether you join from the terminal or the browser — it's billed once per call, not per person.
Related [#related]
# Computer control from the CLI
`nebula-ai local-device enable` turns the machine you're on into a [local device](/docs/devices/local-device) your agents can use. It's the headless counterpart to the [desktop app's](/docs/desktop/computer-control) Computer Control — same result, no window required, which is what makes it the right tool for a server or a dev box you reach over SSH.
It takes the directory you ran it from as the working folder without printing a line about it. Pass `--primary-folder ` to name one explicitly and it confirms with `Working folder set to `.
What enabling does [#what-enabling-does]
One command does four things, in this order.
Signs you in, if you aren't already.
Uses **the folder you ran it from** as the working folder. Pass `--primary-folder ` to point somewhere else.
Registers this machine as a device in your active workspace.
Starts the daemon that lets agents reach it.
Run it from the directory you actually want agents working in. It takes the current directory silently, so `cd` first.
A local device starts **private to whoever registered it** — nobody else in the workspace can see it or send work to it, not even the workspace owner. Only its owner can change that, by [adding named teammates](/docs/devices/local-device#sharing-your-computer-with-teammates) from the web app. There's no CLI command for it, and no admin override.
Whether agents can run commands [#whether-agents-can-run-commands]
Registering a device and letting agents execute commands on it are two separate decisions.
`nebula-ai local-device exec-mode get` prints the current mode. A running daemon picks a change up on its own — you don't need to restart it.
Managing the daemon [#managing-the-daemon]
`nebula-ai local-device status` reports whether computer control is on, which workspace the device belongs to, and whether the daemon is running.
`start`, `stop`, and `restart` do what they say. `nebula-ai local-device logs` shows what the daemon has been doing.
`nebula-ai local-device disable` turns computer control off and stops the daemon, leaving the device registered. `uninstall` goes further and removes the device too.
The daemon runs only while computer control is on. It does **not** reinstall itself as a system service and does **not** survive a reboot — start it again after one, or re-run `enable`.
When status and reality disagree [#when-status-and-reality-disagree]
`status` asks the server where this machine is actually attached and prints the
answer on a **Server:** line, rather than guessing from local state. That matters
because a machine serves **one workspace at a time** — so enabling it from a second
workspace moves it, it doesn't add it.
When the two don't line up, `status` says so and names the fix:
| What it tells you | What to do |
| ------------------------------------------- | ------------------------------------------- |
| The device is attached to another workspace | Re-run `enable` from the workspace you want |
| The server has no such device | Re-register with `enable` |
| Known, but not serving any workspace | Attach it with `enable` |
| The credentials were rejected | Sign in again with `nebula-ai login` |
The recovery is the same command each time — `nebula-ai local-device enable`, run
from the workspace you want this machine to serve. Enabling from somewhere else is
now the only thing that moves it; background reconnects leave your choice alone.
Seeing more than one workspace under **Enabled in**? That's expected, and it isn't a
contradiction — the machine can be *enabled* in several, but only the one on the
**Server:** line receives commands.
The working folder [#the-working-folder]
The working folder is where agents read and write by default. On the CLI it
tracks **the directory you launched from**, but only among folders you've
already approved — the CLI keeps a list of the ones you said yes to, and a
separate list of the ones you said never to. Land in a folder that's on neither
list and it asks. What differs per surface is whether Nebula takes the folder or
asks for it.
Open `nebula-ai` in a folder it hasn't seen and it **asks first** —
*Work in this folder?* — with three answers: **Yes, work in this folder**,
**Not now** (it asks again next launch), or **Never for this folder**. Only
*never* is remembered as a refusal; *not now* lasts the session. Until you
say yes, the agent works in the cloud sandbox rather than on your machine.
`nebula-ai chat` asks the same question at the prompt, as
`Work in ~/code/api? [Y/n/never]` — Enter accepts, and only the literal word
`never` opts into permanence. It skips the question entirely under `--json`
or when there's no terminal attached, and skipping isn't recorded as a
refusal.
`nebula-ai local-device enable` doesn't ask — it takes the folder you ran it
from, unless `--primary-folder ` says otherwise.
An [ACP editor session](/docs/cli/reference#using-nebula-from-your-editor)
uses the directory the editor opened it in, without asking.
Saying yes can do more than point the agent at a folder. If Computer Control
was off, answering *Yes, work in this folder* **turns it on**, scoped to that
folder and lasting while Nebula is open — the prompt says so on the option
itself. If you only want the agent to start there without granting anything
new, that's what the second line of the option describes.
So you change it by going somewhere else and starting again — and saying yes
when it asks. Inside the app, the line above the composer always names where the
next message will run, and **`Ctrl+O`** re-opens the question. That shortcut is
offered only while you're in the cloud sandbox; once you're working on your
machine there's nothing left to ask.
This is where the CLI and the [desktop app](/docs/desktop/computer-control)
differ. The desktop app lets you pick a folder outright; the CLI takes its cue
from where you start it. They write the same setting, so starting the CLI
somewhere else can repoint the folder you chose in the app. It asks you first —
unless you'd already approved that folder, in which case it repoints silently.
There is a `local-device primary-folder set` hiding in the CLI. It writes the
same stored folder the prompt does, but it's kept out of `--help` for a reason:
launching from a different approved folder repoints it underneath you, so
what it set doesn't necessarily survive. `cd` to where you want to work and
answer the prompt instead.
Agents can also move themselves within a thread, and that's separate from this machine-level default. An agent can change the folder it's working in, switch the conversation to one of your other [devices](/docs/devices) entirely, or do both at once — and whichever it picks holds for the rest of that thread. Switching machines starts it in that device's home folder rather than carrying the old path across, since a path from one machine rarely means anything on another.
Related [#related]
# Nebula CLI
`nebula-ai` puts your whole workspace in the terminal — the same agents, channels, threads and calls you get in the browser, without leaving your shell. Run it with no arguments for a full-screen app, or with a command to do one thing and exit.
Install it [#install-it]
```sh
npx nebula-ai
```
The first run downloads the binary for your platform, verifies it, and caches it. After that it starts instantly.
```sh
brew install agent-labs-dev/nebula/nebula-ai
```
Installs `nebula-ai` onto your `PATH` so you can run it from anywhere.
Sign in [#sign-in]
Run `nebula-ai login`. It uses device-flow pairing, so the terminal shows you a code and hands off to your browser.
Approve it in the browser with the same account you use on the web.
You're done. Run `nebula-ai` on its own to open the app, or go straight to a command.
Unlike the [desktop app](/docs/desktop), the CLI does **not** renew its pairing on its own. When a code expires it tells you to run `nebula-ai login` again — that's expected, not a fault.
Two ways to run it [#two-ways-to-run-it]
"] },
{ label: "Best for", values: ["Working in Nebula for a while", "Scripts, CI, a quick question"] },
{ label: "Machine-readable", values: ["—", "yes, with --json"] },
{ label: "Interactive", values: ["yes", "only where the command asks"] },
]}
/>
Anything with no arguments opens the app; anything with arguments runs and exits. See the [command reference](/docs/cli/reference) for the full list.
There's a third mode: `nebula-ai acp` hands the whole thing to your editor
instead of your shell. See [using Nebula from your editor](/docs/cli/reference#using-nebula-from-your-editor).
Getting around the app [#getting-around-the-app]
The app is keyboard-driven and modal, like a modal editor. In **navigation mode** the keys move you around; press i to start typing and Esc to come back out. The bar along the bottom always names the mode you're in and the keys that matter on this screen.
| Key | What it does |
| ---------------------------- | -------------------------------------------------------- |
| ? | Opens the shortcuts help — the full list, always current |
| Ctrl K | Search across your workspace |
| j / k | Move down / up |
| Enter | Open the selected item |
| Esc | Go back, or leave typing mode |
| i / c | Write a message / start a call |
| Ctrl F | Find in the thread you're reading |
| @ | Jump to Agents |
| b | Jump into the sidebar |
| q | Quit |
Don't memorise these — ? lists every shortcut for the screen you're on, including ones this page doesn't cover.
The home screen [#the-home-screen]
Home is a starting point, not a feed. You get the Nebula orb, a **Talk to Nebula** entry that starts a call, and the composer. Press i to write, c to call, and Tab to move between the workspace line at the top, the call entry, and the composer.
The line under the composer shows which [model tier](/docs/models) will answer — Shift M cycles it. Where a message will actually run is named at the top of the screen instead: **Computer Control** sits on the right of the workspace line, **on** or **off** for the workspace you're in. Send from here and it runs wherever that says — on your machine if you've [approved this folder](/docs/cli/computer-control#the-working-folder), in the cloud sandbox otherwise.
The sidebar [#the-sidebar]
The left column mirrors the web app's sidebar: **Home**, **Notifications**, **Agents**, **Jobs**, **Mini Apps**, **Calls**, **Devices**, **Settings**, then your channels and recent threads. Rows carry the same signals you'd expect — an unread count, a dot while an agent is working, a marker when something needs you.
Press b, or press ← from the leftmost tab. Then j / k to move and Enter to open — which hands focus back to the main area.
Ctrl B rests it as a narrow rail, and again brings it back. Nebula remembers which you prefer.
Below about 100 columns it starts as the rail on its own, showing a single › at the left edge. Press b to peek it open — it returns to the rail when you leave.
Finding something in a long thread [#finding-something-in-a-long-thread]
Ctrl F opens a find bar over the thread you're reading. Type and it counts the hits as you go — `3/12` — or says **no matches**. Enter and Ctrl N move to the next hit, Ctrl P to the previous, and Esc closes the bar and leaves you where you landed. It searches the thread you're in, not the workspace — Ctrl K is the one for that.
Two places tell you where work runs [#two-places-tell-you-where-work-runs]
The terminal names the machine twice, and they answer different questions. Read them as *next* and *now*.
They agree most of the time. They come apart when you open a thread that started somewhere else — a thread run on your laptop, opened from a terminal in the cloud sandbox — and that's exactly when you want to notice.
Tabs [#tabs]
The app keeps tabs, the same way the web app does. 1–9 jump to a tab, h and l step between them, and x closes the current one. Home can't be closed.
Slash commands [#slash-commands]
Typing `/` in the composer opens the same [slash commands](/docs/slash-commands) you get on the web — Tab completes a name, Enter runs it. Pressing c on a message that mentions a command explains it instead of running it.
Picking a workspace [#picking-a-workspace]
Your session has an active workspace, and every command uses it unless you say otherwise.
`nebula-ai workspace switch ` changes the active workspace for everything that follows.
The global `--workspace` flag overrides it for a single command, which is what you want in a script.
`nebula-ai workspace list` prints them all; `nebula-ai status` shows who you're signed in as and where you're pointed.
What it can't do [#what-it-cant-do]
The CLI drives the same backend as everything else, so the gaps are narrow and deliberate. The one you'll hit in practice is that actions needing a choice — picking a channel or a workspace from a list, renaming a connection — are refused with a note to use the web app instead. Everything else in `nebula-ai integrations` works from the terminal.
Stuck? Ask Nebula in any conversation — it can explain commands and set things up for you. For bugs or anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# Command reference
Every `nebula-ai` command, what it does, and the flags that apply everywhere. Run `nebula-ai --help` for the options on any one of them — that output is generated from the binary you have, so it's always current.
Commands [#commands]
| Command | What it does |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `login` | Authenticate with Nebula via device-flow pairing |
| `logout` | Clear stored credentials |
| `status` | Show CLI status overview |
| `usage` | Show workspace token usage and cost — `--days ` sets the window |
| `chat` | Send a message to an agent DM and stream the response |
| `call` | [Voice calls](/docs/cli/calls) — see [below](#calls) |
| `channels` | Manage channels (threads) — see [below](#channels) |
| `agents` | Manage agents — see [below](#agents) |
| `workspace` | Manage workspaces — `list`, `switch`, `create` |
| `integrations` | Connect and manage workspace integrations — see [below](#integrations) |
| `user` | Your profile and account settings — see [below](#account-commands-live-under-user) |
| `profile` | Your public profile — `get`, `set`, `set-email`, `verify-email`, `upload-avatar` |
| `local-device` | [Manage computer control](/docs/cli/computer-control) and the local device daemon — see [below](#local-device) |
| `install` | Set up computer control — an alias of `local-device enable` |
| `uninstall` | Turn off computer control, stop the daemon, and remove this device |
| `capabilities` | Probe and print this host's capability snapshot |
| `logs` | Inspect Nebula log files on disk — `logs path` prints the directory |
| `update` | Check for a newer CLI version and install it |
| `completion` | Generate a shell completion script |
| `acp` | Run Nebula as an [editor agent](#using-nebula-from-your-editor) over the Agent Client Protocol |
Run `nebula-ai` with no command at all to open the [full-screen app](/docs/cli).
Agents [#agents]
Everything except `list` and `create` takes the agent's ID as its first argument.
| Command | What it does |
| ---------------------- | --------------------------------------------------------------- |
| `agents list` | List agents |
| `agents create` | Create a new agent |
| `agents get` | Get agent details |
| `agents update` | Update an agent |
| `agents delete` | Delete an agent |
| `agents enable` | Enable an agent |
| `agents disable` | Disable an agent |
| `agents logs` | Get agent logs |
| `agents errors` | Get agent errors |
| `agents triggers` | List triggers for an agent |
| `agents accounts` | Show which account an agent acts as, and what else it could use |
| `agents set-account` | Choose which connected account an agent acts as |
| `agents skills list` | List skills attached to an agent |
| `agents skills detach` | Detach a skill from an agent |
An agent doesn't pick up your connected accounts on its own — you choose one per
app. `agents accounts ` is how you see where that stands from a terminal: it
lists your connected accounts with an **In use** column, so a connected account
reading `no` is exactly what a stalled tool is waiting for.
The toolkit is implied by the account you name, so there's no separate flag for
it. Only the agent's owner can set this — the binding decides which of *their*
identities the agent spends.
{/* cli-audit-ignore: agents skills attach — named here only to say it does not exist */}
There's no `agents skills attach`. Attaching a skill by name was removed from
the backend — install one from the public registry or upload a skill file
instead, both of which you can ask Nebula to do for you.
Channels [#channels]
| Command | What it does |
| -------------------- | ----------------------------- |
| `channels list` | List channels |
| `channels create` | Create a new channel |
| `channels get` | Get channel details |
| `channels status` | Show the thread's work status |
| `channels update` | Update a channel |
| `channels messages` | List messages in a channel |
| `channels share` | Share a channel |
| `channels archive` | Archive a channel |
| `channels unarchive` | Unarchive a channel |
| `channels delete` | Delete a channel |
`nebula-ai chat --resume ` skips all of this and opens that channel
directly in the full-screen app.
Calls [#calls]
The [calls page](/docs/cli/calls) covers what each of these feels like to use.
| Command | What it does |
| ---------------------- | ---------------------------------------------- |
| `call start` | Start a call and open the call screen |
| `call join ` | Join an existing call |
| `call list` | List active calls |
| `call status ` | Show the state of one call |
| `call chat ` | Send a one-shot typed message into a live call |
| `call leave ` | Leave a call you're in |
| `call end ` | End the call for everyone |
Integrations [#integrations]
| Command | What it does |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `integrations list` | List integration connections |
| `integrations connect ` | Connect a workspace integration |
| `integrations disconnect [account]` | Disconnect a workspace integration account. The account ID is only needed when more than one is connected |
Models [#models]
Which models this workspace can use, and which one it falls back to. Curating the
catalog and setting the default need workspace admin or owner; listing doesn't. See
[Models and defaults](/docs/models).
| Command | What it does |
| --------------------------------- | ---------------------------------------------------------- |
| `models list` | List selectable models — Nebula tiers, curated, and custom |
| `models default [model]` | Show the workspace default, or set it (admin only) |
| `models curate` | Show which vendor models the workspace offers |
| `models curate --add ` | Add vendor models to the curated list |
| `models curate --remove ` | Remove vendor models from the curated list |
| `models custom list` | List custom models visible in this workspace |
| `models custom add` | Add a custom model — see the flags below |
| `models custom remove ` | Delete a custom model you own |
`models custom add` takes `--alias ` to create a routing alias to a catalog
model, or `--base-url ` with `--model-id ` to point at your own
OpenAI-compatible endpoint. Add `--auth ` for an authorization header,
`--device ` to lock the model to one machine, and `--share` to make it
visible to the whole workspace instead of just you. See
[Bring your own model](/docs/models/custom) for what each of those means.
Local device [#local-device]
The [computer control page](/docs/cli/computer-control) explains when you'd reach for each.
| Command | What it does |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `local-device enable` | Turn on computer control and start the daemon |
| `local-device disable` | Turn off computer control and stop the daemon |
| `local-device status` | Show computer-control and daemon status, and check with the server which workspace this machine is bound to |
| `local-device logs` | View daemon logs |
| `local-device start` | Start the daemon |
| `local-device stop` | Stop the daemon |
| `local-device restart` | Restart the daemon |
| `local-device exec-mode get` | Show the current execution mode |
| `local-device exec-mode set ` | Set whether agents can run commands on this host |
Account commands live under user [#account-commands-live-under-user]
Anything that belongs to your account rather than the workspace is nested one
level down, so `nebula-ai user` on its own prints a summary of who you're
signed in as.
| Command | What it does |
| ---------------- | ---------------------------------------------------------- |
| `user update` | Update your username or display name |
| `user variables` | Manage user variables — `list`, `set`, `create`, `delete` |
| `user config` | Manage CLI configuration — see [below](#cli-configuration) |
| `user billing` | Manage credits — `balance`, `history`, `auto-topup` |
| `user files` | Manage files — see [below](#files) |
| `user devices` | Manage your cloud devices — see [below](#cloud-devices) |
CLI configuration [#cli-configuration]
| Command | What it does |
| ------------------------------- | ------------------------------ |
| `user config list` | List all configuration values |
| `user config get ` | Get a configuration value |
| `user config set ` | Set a configuration value |
| `user config reset` | Reset all settings to defaults |
| `user config models` | List available AI models |
`user config set telemetry false` turns product analytics off. The
[`DO_NOT_TRACK`](#environment-variables) environment variable does the same
thing without touching your config.
Files [#files]
| Command | What it does |
| -------------------------- | ------------------------------- |
| `user files list` | List files |
| `user files get ` | Get file details |
| `user files content ` | Print a text file's contents |
| `user files upload ` | Upload a file |
| `user files download ` | Download a file |
| `user files share ` | Create a shared link for a file |
| `user files folders` | List folders |
| `user files delete ` | Delete a file |
Cloud devices [#cloud-devices]
These are your [cloud devices](/docs/devices), not the machine you're typing on
— that one is `local-device`.
| Command | What it does |
| --------------------------------------- | ------------------------------------------------------------- |
| `user devices info` | Get your device info |
| `user devices start` | Start your device |
| `user devices stop` | Stop your device |
| `user devices rename ` | Rename your device |
| `user devices visibility ` | Make the device visible to your workspace, or keep it private |
| `user devices files` | List files on the device |
| `user devices search ` | Search device files by filename glob |
| `user devices delete` | Delete your device |
| `user devices services list` | List device services |
| `user devices services get ` | Get service details |
| `user devices services create ` | Create a long-running service |
| `user devices services start ` | Start a service |
| `user devices services stop ` | Stop a service |
| `user devices services logs ` | Get service logs |
Changing your email address [#changing-your-email-address]
Your email is the one profile field you can't set outright — changing it takes
proof that you can receive mail at the new address, so it runs in two steps.
Run `nebula-ai profile set-email `. Nebula mails a six-digit code
to the **new** address and tells you your current address hasn't changed yet.
Run `nebula-ai profile verify-email ` with the code from that mail.
Only then does the address actually change.
Codes expire after 15 minutes; request another with `set-email` if yours runs
out. `nebula-ai profile get` marks an address that hasn't been confirmed yet
with **(unverified)**.
`nebula-ai profile set --email` no longer works and will tell you so. Use the
two commands above instead.
Using Nebula from your editor [#using-nebula-from-your-editor]
`nebula-ai acp` runs Nebula as an agent over the **Agent Client Protocol**,
speaking on standard input and output rather than drawing anything itself. Point
an editor that speaks ACP at that command and Nebula answers inside the editor,
with the same agents and channels you get everywhere else.
Each session is scoped to the directory the editor opens it in, and that
directory becomes the working folder the agent reads and writes in. The scoping
comes from [computer control](/docs/cli/computer-control), so run
`nebula-ai local-device enable` first — without a registered device, sessions
fail with *"Nebula local device is not configured."*
Run it by hand and it will sit there silently waiting for protocol messages.
That's correct behaviour, not a hang — press Ctrl C to exit.
Global flags [#global-flags]
These work on every command.
| Flag | What it does |
| --------------------- | --------------------------------------------------------- |
| `--json` | Output raw JSON |
| `--workspace ` | Run against a specific workspace, ignoring the active one |
| `-v`, `--verbose` | Verbose output — the same as `--log-level=debug` |
| `--log-level ` | One of `error`, `warn`, `info`, `debug`, `trace` |
| `--no-color` | Disable colours |
| `--api-url ` | Point at a different API host |
Environment variables [#environment-variables]
Useful when you can't pass flags — CI, containers, a shared shell profile.
| Variable | What it does |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `NEBULA_AUTH_TOKEN` | Use a pre-minted token instead of the stored credential. Takes precedence over whatever `login` saved |
| `NEBULA_API_BASE` | Point at a different API host — the same thing `--api-url` does |
| `NEBULA_WEB_URL` | Point at a different web app, for the links the CLI hands off to |
| `NEBULA_HOME` | Override `~/.nebula`, where credentials, settings, and logs live |
| `NEBULA_LOG_LEVEL` | One of `error`, `warn`, `info`, `debug`, `trace` — the env form of `--log-level` |
| `NEBULA_DEBUG` | Set to `true` for verbose logging — the same as `-v` |
| `DO_NOT_TRACK` | Set to `1` to turn product analytics off. `NEBULA_DO_NOT_TRACK` works too |
| `NEBULA_AI_NO_UPDATE_CHECK` | Set to `1` to skip the daily update check |
| `NEBULA_AI_CACHE_DIR` | Override where `npx nebula-ai` caches the downloaded binary |
| `NEBULA_AI_DOWNLOAD_BASE` | Download that binary from a mirror instead — useful behind a strict firewall |
`NEBULA_AUTH_TOKEN` is the one to reach for in CI. It skips the device-flow
browser handoff entirely, which a build agent can't complete anyway.
Scripting [#scripting]
`--json` turns any command into something you can pipe. It's a global flag, so it works the same everywhere.
List commands emit a top-level array under `--json`, so `.[]` is the right entry point rather than reaching through a wrapper.
Field names come from the API, not from the table you see. The columns a command prints are often friendlier labels over differently-named fields — and some, like a call's title, aren't fields at all. Run the command once with `--json` and read the shape before writing the `jq`.
Combine `--json` with `--workspace` in CI so a script never depends on whichever workspace happened to be active on that machine.
Shell completion [#shell-completion]
`nebula-ai completion` prints a completion script for `bash`, `zsh`, or `fish` — source it from your shell profile.
~/.nebula-completion.zsh" },
{ kind: "hint", text: "# then add: source ~/.nebula-completion.zsh" },
]}
/>
When something goes wrong [#when-something-goes-wrong]
`nebula-ai status` shows whether you're signed in and which workspace you're pointed at — most surprises are one of those two. `nebula-ai capabilities` reports what this machine supports, like whether `ffmpeg` is available for camera.
`nebula-ai logs path` prints the directory the log files live in (`~/.nebula/logs/`), ready to pipe into your pager. Re-run a failing command with `-v` for the detail.
`nebula-ai update` checks for a newer version and installs it. Worth trying before reporting anything.
Still stuck? Ask Nebula directly — it's good at drafting a support email with the right detail in it. For bugs or anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# The Capsule
The Capsule is a small always-on-top surface that tells you what your agents are doing without you opening Nebula. It watches **every workspace you're a member of**, not just the one you have open.
It's on by default, sitting at the top centre of your screen.
What it looks like [#what-it-looks-like]
The Capsule spends most of its time as a small resting shape and grows only when something happens.
A small lozenge with two counts: how many runs are going right now, and how many finished results you haven't read.
A card peeks out to say a run started or finished, then folds away on its own after a few seconds. Several things at once merge into one card rather than stacking up. Hover to stop the clock while you read.
Hover the resting shape to open the full panel, or click to pin it open. Inside is a single **Threads** lane — one list, with whatever is live or waiting on you sorted to the top — plus a **Mine** / **All** switch beside the heading and a link to open Nebula proper at the bottom.
Two things don't fold away on their own — an agent that **needs you** and a **live call**. Anything blocking work stays put until you deal with it.
Reading the colours [#reading-the-colours]
The Capsule says most of what it has to say without words. A handful of colours carry the whole language, and they mean the same thing everywhere they appear — on the orb, on a card, and on every row in the panel.
| Colour | Means | Where you'll see it |
| ----------------- | ------------------------------------ | -------------------------------------------------------------------- |
| **Blue**, pulsing | Something is running right now | Working rows, the running count on the orb |
| **Amber**, still | Something is waiting on **you** | Unread results, an agent needing an answer, a workspace reconnecting |
| **Green** | You're on a live call | The live-call row, the voice indicator |
| **Grey** | Settled — nothing being asked of you | Finished and read rows |
The useful shorthand: **blue is Nebula working, amber is Nebula waiting on you.** If there's no amber anywhere, nothing needs you.
This is the same colour language the Nebula app uses everywhere else, so a blue dot means the same thing in the Capsule as it does in your sidebar.
Movement means live [#movement-means-live]
Colour tells you the kind of thing; movement tells you whether it's happening *now*.
A gently pulsing blue dot is work in progress. The aurora sphere at the centre of the orb also turns faster and breathes while agents are running, so a busy Capsule looks busy from across the room.
Amber never pulses. A result waiting for you isn't urgent in the same way, so it sits still rather than competing with live work for your attention.
After about seven quiet seconds the whole Capsule dims down to stay out of your way. It brightens the moment something changes, or when you move your pointer near it — so a faded Capsule means "nothing has happened in a while", not "nothing is running".
The orb's own signals [#the-orbs-own-signals]
The resting orb physically grows and shrinks with what it has to report — narrowest with nothing to say, wider with one count, widest with both. You can read it peripherally without focusing on the numbers.
The little aurora sphere is always there. Turning slowly means idle; turning faster with a soft green glow means agents are working.
A thin amber ring around the sphere means results are waiting and nothing is currently running — the state where the only thing outstanding is you.
Dots, badges, and bars [#dots-badges-and-bars]
Inside cards and panel rows, the same language shows up in smaller pieces.
| Indicator | Means |
| ----------------------------- | --------------------------------------------------- |
| Pulsing green dot | Working right now |
| Live dot | A call is running |
| Amber dot | Needs your answer |
| A number | How many messages you haven't read |
| Amber dot in the panel header | A workspace is reconnecting, so counts may be stale |
The header's amber dot clears itself once the connection comes back — you don't have to restart anything.
What a row tells you [#what-a-row-tells-you]
A row is deliberately spare — a state dot, the title, and one thing on the right. It's a list of places to go, not a feed to read, so there are no timestamps and no summaries.
The dot leads, and it says exactly one thing: **green** for a live call, **amber** if the row is unread or waiting on you, **blue and pulsing** while it's being worked on. A settled row carries no dot at all, and its title starts flush at the row's left edge — so the rows that need you are the only ones that break the margin.
The title comes next, followed by a small glyph when the thread belongs to a job, an agent, or a miniapp. On the right sits a badge naming the workspace the row belongs to, useful when you're in more than one. Hover the row and that slot becomes the row's quick action.
Rows don't carry a count of unread messages. *How many* replies are waiting is noise next to the fact that any are — so an unread row goes amber and bold, and leaves the counting to the orb and the panel header.
Working from the panel [#working-from-the-panel]
Clicking a row takes you where that thread actually lives rather than to a generic chat view.
| Row | Opens |
| --------------------- | ----------------------------------------------- |
| A live call | The call room |
| A job | That job's own page, with its runs and schedule |
| An agent conversation | The agent's page |
| A miniapp thread | The miniapp |
| Anything else | The thread, in its channel |
Clicking an unread row marks it read. Clicking a live row just opens it — it won't interrupt the run. The **✕** dismisses a card you're done with.
If a thread belongs to a different workspace than the one you have open, clicking it opens that thread in its own window rather than switching your whole app over.
A request for your approval stays put until you answer it, even while the agent keeps working and talking around it. It won't quietly disappear on you.
Calls in the Capsule [#calls-in-the-capsule]
You can start a [call](/docs/live) from the Capsule, not just control one that's already going. The fastest way in is **QuickLive** — ⌘ ⇧ C from any app. With no call running it starts a one-to-one call with your Nebula and puts you on the mic; with one already going it brings that call back up.
The in-call card [#the-in-call-card]
For as long as you're on a call, the resting orb is replaced by a steady card that stays put. It doesn't fold away and it doesn't grow on its own.
The top line is the call itself — a live dot and the call's title, with fresh captions and dispatched work rotating through as they happen. The bottom line is the working half: how long the call has been running, a **Screen aware** dot when the agent can see your screen, whoever is talking right now, and three controls — **mute your microphone**, **share your screen**, and **leave the call**.
Those three are the ones worth having a click away mid-sentence. Muting the agent's audio isn't among them — that's a setting you choose once, so it lives in the live view's toolbar instead.
The far end of that line keeps you in touch with everything the call isn't. Counts appear there when work is running or messages are unread, and a **Show other activity** button sits beside them — the one control on that side that's always there, whether or not the call has anything to report.
Talkers show as a short row of small round faces — people first, then agents, up to four at once. It's empty when the call is quiet, so a glance tells you whether anyone is actually speaking.
When someone shares their screen [#when-someone-shares-their-screen]
A live screenshare takes priority over the talker faces: the card swaps them for a **You're presenting** or **Ana presenting** chip, or **3 presenting** when several people are sharing at once. Click it to open the call and watch.
Open the live view and the same thing reads as a full-width banner — *"Ana is sharing their screen"* — with a **Watch** chip on the end.
Click the card body and the live view opens out of it, in place. From there **Open the full room** moves the call into its own window.
Moving a call into its own window hands it over rather than reconnecting — you stay on the call throughout. It arrives muted, so unmute once the window comes up.
The live view carries the whole call in one column: what people said, anything typed, and your agent's activity in the order it happened. There's a composer at the bottom, so you can take part by typing without going on voice at all.
Everyone on the call sits in a row of faces across the top, each captioned with that person's first name and wearing their profile picture. Faces shrink as the call fills up so a dozen people still fit on one line; past that, the extras collapse into a single **+3**-style tile at the end. Agents sit in the same row but wear their live orb instead of a face. Activity lines name people too — you'll read **Joaquim joined** rather than a nameless placeholder.
While it's open you can drag it anywhere on screen and it stays where you drop it — it won't snap back to its corner, and clicking elsewhere won't fold it away mid-call. Collapse it, press Esc, or end the call and the Capsule returns to its usual spot.
Settings [#settings]
Open the gear in the panel header.
| Setting | What it does |
| ---------------- | ------------------------------------------------------------ |
| **Position** | Pick which of six screen corners and edges it lives in |
| **Threads** | **All** activity in your workspaces, or just **Mine** |
| **Size** | Small, medium, or large |
| **Workspaces** | Mute individual workspaces so their activity doesn't surface |
| **Show capsule** | Turn it off entirely |
On a shared screen, mute the workspaces you're not presenting — or turn the Capsule off from the same menu.
Notifications on desktop [#notifications-on-desktop]
The Capsule *is* the notification system on desktop. The app doesn't post operating-system notifications, so nothing lands in macOS Notification Center or the Windows action center — activity surfaces in the Capsule and in your Nebula inbox instead.
Email, mobile push, and chat-app delivery all still work as configured. See [Notifications](/docs/notifications).
Related [#related]
The same window, in composer mode — send to Nebula from anywhere.
Install, sign in, and updates.
Inbox, delivery destinations, and rules.
How calls work, in the browser and on desktop.
# Turn on Computer Control
Computer Control turns your machine into somewhere agents can actually do work: read and write your files, run commands, and reach things only your computer can reach. You choose how long it stays on and how far it reaches, and you can take it back at any time.
What it unlocks [#what-it-unlocks]
Without Computer Control, Nebula still does plenty — it just does it all in the cloud. Turning it on adds the things that only make sense on *your* machine.
Agents work on real files on your disk — reorganize a directory, batch-rename exports, read a spreadsheet you'd rather not upload anywhere, or write results straight back where your other software expects them.
Anything installed locally is fair game — your dev environment, your CLI tools, a build or test suite, software you've configured over years and don't want to recreate in the cloud.
Internal sites, a staging server behind the VPN, a database only reachable from your machine. If your computer can reach it, an agent working there can too.
[Quick Send](/docs/desktop/quick-send) can attach a picture of what you're looking at, so you can ask about the thing in front of you instead of describing it.
Once it's on, you route work to your machine by asking — *"use my local Mac for this"*, or *"run the test suite in my project folder"*.
Opening the controls [#opening-the-controls]
A **Computer Control** row sits at the bottom of the sidebar, with a coloured dot on its icon so the current state is always visible. Click it to open the panel. The row only appears in the desktop app — in a browser there's nothing to control, so it isn't there.
| Dot | Meaning |
| ----- | ------------------------------------- |
| Grey | Off — agents can't touch this machine |
| Green | On while Nebula is open |
| Blue | On even when Nebula is closed |
The panel opens with a plain-language banner confirming where you stand — *"Computer control is on in this workspace"*, and underneath, that agents in this workspace can run commands and read files on this computer. When it's off, it says so just as plainly.
How long it stays on [#how-long-it-stays-on]
Three choices, as a single row of buttons.
This choice applies to **the workspace you're in**. The panel tells you how many workspaces this computer is enabled in, so you can see at a glance whether you've switched it on somewhere else too.
With **Off**, Nebula still works — chat, cloud devices, and connected apps all carry on. You just don't get anything in the list above.
How far it reaches [#how-far-it-reaches]
Separate from *how long*, there's **how much** — and this one is worth reading carefully.
The default. Agents can reach anywhere your user account can, and the working folder is simply where commands start from — not a fence.
Confines agents to the working folder and what's inside it. Click **Limit to working folder** to switch, then click again to confirm.
Because **Whole system** is the default, choosing a working folder does **not** by itself keep agents inside it. If you want that boundary, set it explicitly with **Limit to working folder** — and turn on the [safety gate](/docs/settings/approvals) if you'd rather approve writes and deletes as they come.
Going the other way — from a confined folder back out to the whole machine — also takes two clicks, so access never widens by accident.
The working folder [#the-working-folder]
**Working folder** is where an agent's commands run from, shown in full so there's no guessing which directory you're pointed at. **Change…** picks a different one.
Point it at a project folder or a dedicated working directory rather than your home folder. Agents pick up the change straight away.
Your choice sticks until you use the [CLI](/docs/cli/computer-control#the-working-folder), which points the working folder at the directory you run it in. Both write the same setting, so the last one to start wins — though the CLI asks before it repoints, unless you'd already approved that folder there.
Checking on it [#checking-on-it]
The panel doubles as a status readout when something isn't behaving.
| Row | What it tells you |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| **Daemon** | Whether the background helper is running, and which app is looking after it — the desktop app or the CLI |
| **Enabled in** | How many workspaces this computer currently serves |
| **Access** | Whole system, or working folder only |
| **Working folder** | The directory commands run from |
| **Device ID** | This machine's identifier, handy when asking support about a specific computer |
**View logs** tails the helper's log right in the panel, and **Open logs folder** reveals the files on disk — the first thing to reach for if an agent says it can't reach your machine.
Which workspaces it serves [#which-workspaces-it-serves]
Access is granted per workspace, not once and for all. The desktop app's **Settings → Workspaces** lists the workspaces you're in with a toggle for each — so your machine can serve your own workspace while staying invisible to a client's.
When it's actually running [#when-its-actually-running]
The dot on the sidebar row is the quickest read — grey, green, or blue. Hovering it spells the state out: **Computer Control: Off**, **On while Nebula is open**, or **Always on**.
On **While Nebula is open**, quitting stops agents reaching your machine, and Nebula warns you first since a scheduled job that expects this computer will start failing. On **Even when closed**, the helper keeps running without you.
Rebooting doesn't bring the helper back on its own — open the app again and it picks up where it left off.
The desktop app isn't the only way. The Nebula command-line tool can run the same helper with `nebula-ai local-device enable`, which suits a headless machine or a server. Whichever one starts it owns it — the **Daemon** row names the owner, and the other surface shows it as managed elsewhere rather than fighting over it.
Permissions your computer asks for [#permissions-your-computer-asks-for]
Fewer than you might expect. Nebula asks the operating system for something only when you first use the feature that needs it.
| Feature | What your system asks for |
| ----------------------------------------------- | ----------------------------------------------------------- |
| Voice calls | Microphone access, the first time you speak on a call |
| Screen aware, and sharing your screen on a call | Screen recording access, the first time you use it |
| Agent file and command access | Nothing from the OS — scope is the **Access** setting above |
Related [#related]
Your computer as something agents can be pointed at.
Gate the writes and deletes an agent makes on your machine.
Screen aware, and sending from any app.
Which workspaces this computer serves.
# Nebula Desktop
The Nebula desktop app gives you everything the web app does, plus a set of things a browser tab can't: a corner view of what your agents are doing, a global shortcut to send from any app, and the ability to let agents work on your own computer. If you'd rather stay in a terminal, the [CLI](/docs/cli) covers the same ground without a window.
**[Download Nebula Desktop](https://www.nebula.gg/download)** — free, for macOS, Windows, and Linux.
The window itself is the Nebula you already know. The two things you can't get in a browser are visible here: the **Computer Control** row at the bottom of the sidebar, and the [Capsule](/docs/desktop/capsule) floating above everything in the corner.
What desktop adds [#what-desktop-adds]
Desktop runs the same Nebula you already know — same channels, agents, jobs, and settings. What's different is the native shell around it.
Let agents run real work on your own machine, in a folder you choose.
An always-on-top view of live agent activity across every workspace you're in.
A global hotkey that opens a composer over whatever you're doing.
Hotkeys, the macOS menu bar icon, and pop-out windows.
Settings that belong to this computer rather than your account.
Install it [#install-it]
Head to [nebula.gg/download](https://www.nebula.gg/download) — it hands you the right build for the machine you're on, and it's also where the [Nebula CLI](/docs/cli) and the [mobile app](/docs/mobile) live.
A signed, notarized app for both Apple silicon and Intel Macs. Requires macOS 13 or later. Drag it to Applications and open it.
An installer for Windows 10 and later, installed for your user account rather than machine-wide. Windows may show an "unrecognized app" warning on first run — choose **More info → Run anyway**.
An AppImage, plus a pacman package. On Arch you can install `nebula-desktop-bin` from the AUR and let your package manager handle updates.
Sign in [#sign-in]
Desktop signs in by pairing rather than by password. The app shows you a short code, opens your browser, and waits.
Open the app. It displays a pairing code in the form **XXXX-XXXX**.
Your browser opens Nebula's activation page. Sign in there if you aren't already.
Confirm the code matches, and approve. The app picks it up on its own and continues.
Codes don't last forever, but running out isn't something you have to handle. If a code expires while you're looking at it, the app quietly fetches a fresh one and shows it in place — and if the window was hidden, it renews the moment you come back to it. **Get a fresh code** is there if you'd rather force it.
Signing in on desktop also signs in the Nebula command-line tool on the same machine — they share one stored credential.
If Nebula ever drops you back to the sign-in screen on its own, it says why — *"Your session expired. Please sign in again."* when the stored credential aged out, or a note that it couldn't read the sign-in saved on this device. Either way the fix is the same: pair again.
Staying up to date [#staying-up-to-date]
Everything arrives together, in the app update, and you don't have to do anything to get it. Desktop checks shortly after launch and every few hours after that; when it finds a new version it downloads it quietly in the background and installs it the next time you quit. Quitting and reopening — something you already do — is all it takes.
You can still push it along by hand. The update item sits in the tray menu and, on macOS, in the **Nebula** menu, and it tells you where things stand:
| Item | What it means |
| ------------------------------- | --------------------------------------------------------------------------------- |
| **Check for updates…** | Nothing waiting. Click to check now |
| **Checking for updates…** | A check is running |
| **Download update to v1.2.3** | Found one — click to fetch it immediately |
| **Downloading update…** | In progress, with a percentage once it's known |
| **Restart to update to v1.2.3** | Downloaded and staged. Click to restart now instead of waiting for your next quit |
| **Update check failed - Retry** | The check didn't complete; click to try again |
There's no pop-up and no confirmation when a check finds nothing — the item simply goes back to **Check for updates…**.
Two exceptions never self-update: development builds, and Linux installs from the AUR, where your package manager owns updates instead.
The Nebula experience inside the window used to refresh on its own, separately from the app version. It doesn't any more — the version you install is the version you run. If a feature you've read about hasn't appeared, make sure you've quit and reopened since the last update.
Release notes for the desktop app appear in **What's New** alongside everything else, so the list always matches the version you actually have installed.
Related [#related]
The corner surface that shows what your agents are doing.
What you unlock by letting Nebula work on your machine.
How your computer becomes something agents can use.
Set up your workspace, first agent, and first channel.
# Quick Send
Quick Send puts a Nebula composer over whatever you're doing. Press ⌘ \` (Mac) or Ctrl \` (Windows / Linux), type, and send — without leaving the app you're in.
The Capsule expands into the composer and flies back to its corner when you send, so you land back where you started.
What happens when you send [#what-happens-when-you-send]
Each send starts a **fresh conversation**. You don't pick an agent — Nebula reads what you sent and routes it to whoever should handle it, exactly like sending from Home.
The Capsule shows the send going out, then picks up the run and reports back when there's something to see. You can carry on with what you were doing.
What you can set on the way out [#what-you-can-set-on-the-way-out]
The composer carries a short row of controls.
Attaches a screenshot of the screen you're pointing at, so you can ask about what's in front of you without describing it. The shot is taken after the composer gets out of the way, so you capture your work rather than the Nebula window. It only appears when you've given Nebula [access to your computer](/docs/desktop/computer-control).
Whether the new thread is visible to your workspace or just to you. It remembers what you last chose.
Picks which [Nebula tier](/docs/models) this one runs on — **Flash**, **Max** or **Ultra**. Quick Send keeps its own choice, remembered on this device, so it doesn't disturb the tier you use in the web app.
The shield toggles your approval gate for writes and deletes. It's the same account setting as in the web app, so changing it here changes it everywhere. See [Approvals](/docs/settings/approvals).
The paperclip attaches files — up to 8 at a time. Images preview as thumbnails. Uploading starts the moment you attach, and sending no longer waits for it to finish: the composer folds away immediately and the upload rides along in the background, so a big file doesn't hold you hostage. The Capsule card narrates **Uploading…** then **Sending…** so you can watch it land.
Because a send finishes after the composer has folded away, the Capsule is where you find out it worked. If something goes wrong — an attachment that wouldn't upload, or a send the workspace refused — the card turns amber and says what happened, in Nebula's own words rather than a generic failure. It stays put until you deal with it: click it to open the thread, or dismiss it with its **×**. Nothing is silently dropped.
**Screen aware** is the reason to reach for Quick Send over a browser tab. Stuck on an error dialog, a chart, or a diff, hit the shortcut and ask "what am I looking at?" without switching windows or taking a screenshot yourself.
Screen aware is one screenshot, not live [#screen-aware-is-one-screenshot-not-live]
Despite the name, Screen aware isn't continuous — it takes **a single still image at the moment you send**, attaches it to that message, and stops there. Your agent sees what your screen looked like then, not what it looks like now.
When you want an agent watching something that changes — stepping through a bug, walking a dashboard, reviewing a document together — [share your screen on a call](/docs/live/screen-sharing) instead. There the agent can take a fresh look every time you ask.
Slash commands [#slash-commands]
[Slash commands](/docs/slash-commands) work here too. Type `/` as the first thing in the composer and a list opens underneath it; keep typing to narrow it, arrow up and down to move, Tab to complete the one you're on, and Enter to send. Esc clears the command; a second Esc folds the composer away.
Commands that need an existing conversation stay in the list rather than vanishing — greyed out, with the reason on hover. Quick Send always starts a fresh thread, so those are the ones you'll see disabled.
A slash command can't carry a file or a screenshot. Attach something to one and Nebula says so and gives you your text back rather than dropping either.
Screen capture permission [#screen-capture-permission]
The first time you use **Screen aware** on a Mac, macOS asks whether Nebula can record your screen. It's the standard system prompt, and you can change your mind later in **System Settings → Privacy & Security → Screen Recording**.
Nothing is captured unless Screen aware is switched on for that send. If a capture fails, your message still goes — it just goes without the picture.
Changing the shortcut [#changing-the-shortcut]
Every global desktop shortcut is re-recordable in **Settings → Shortcuts** in the desktop app. If another app already owns the combination you pick, Nebula keeps your previous one rather than silently doing nothing.
You can also reach Quick Send from the tray menu.
Related [#related]
The surface Quick Send folds back into.
Required for Screen aware, and much else besides.
Every desktop shortcut and the menu bar icon.
The same untargeted send, from the web app.
# Desktop settings
The desktop app has its own settings window, separate from the Nebula settings you'd find on the web. It holds the things that belong to **this computer** rather than to your account.
It's an ordinary resizable window, so you can leave it open beside Nebula while you change things. Everything lives in one scrolling page, and every entry point can drop you straight onto the section you want.
**Settings → Open Settings…** opens the window at the top. The same submenu lists all five sections, so you can jump directly to one.
⌘ , on macOS, the same as any Mac app. There's no equivalent hotkey on Windows or Linux — use the tray.
The gear icon on the [Capsule](/docs/desktop/capsule) opens this window on the **Capsule** section. The Capsule no longer keeps settings of its own.
**Desktop app settings**, at the bottom of the settings nav under *This computer*. It only appears when you're running the desktop app — in a browser there's nothing to open, so it's hidden.
What's in it [#whats-in-it]
**Computer name** — how this machine appears in Nebula. Leave it blank and it uses your computer's own hostname. Worth setting if you run Nebula on more than one machine and "MacBook-Pro-3" isn't telling you much.
**Appearance** — Auto, Light, or Dark. Auto follows your operating system. This one styles the desktop app's own window chrome, and it's a different setting from the [theme](/docs/settings/appearance) you pick for Nebula itself — that's a named palette stored on your account, and it applies inside the desktop app too.
**Share anonymous usage data** — on by default. Turning it off stops the desktop app *and* the Nebula app inside it from sending usage data.
**Hardware acceleration** — on by default, and it renders Nebula with your graphics card. Nebula turns this off by itself if your graphics driver crashes repeatedly, and tells you it has; switch it back on once you've updated the driver. Either way it takes effect the next time Nebula starts.
Three choices for how much access agents get: **Allow using my computer** (works even when Nebula is closed), **Allow only while Nebula is open**, or **Don't allow**. Pick either of the first two and you also get **Access** — *Working folder only* or *Whole system* — and a **Primary folder** to point them at.
This section also reports the helper's status and your **Device ID**, and **View logs** tails what it's been doing. See [Computer Control](/docs/desktop/computer-control) for what each choice unlocks.
Which of your workspaces this computer serves, one toggle each. It only appears once you've allowed agents to use the computer, since there's nothing to serve otherwise.
Everything about the [Capsule](/docs/desktop/capsule) — whether it shows at all, which corner it sits in, its size, which threads it follows, and per-workspace muting. Its gear icon brings you here rather than opening a menu of its own.
The four global hotkeys — **Summon Nebula**, **Quick send**, **QuickLive**, and **Mute microphone**. Click one and press the combination you want. See [Shortcuts & tray](/docs/desktop/shortcuts-and-tray).
The folder agents work out of goes by two names. This window calls the row **Primary folder** but labels the narrow access mode **Working folder only**, and the command-line tool calls it **Working folder** throughout. It's one setting whichever name you meet it under — which is why [running the CLI](/docs/cli/computer-control#the-working-folder) from another directory can repoint the folder you picked here — it asks first, unless that folder is one you've already approved there.
Where the rest of your settings live [#where-the-rest-of-your-settings-live]
Anything tied to **you** rather than to this machine stays in Nebula itself and follows you to every device and the web.
Signing in on desktop also signs in the Nebula command-line tool on this machine — they share one credential. Signing out of one signs out the other.
Related [#related]
The setting that lets agents work on your machine.
The hotkeys and the menu bar icon.
The corner surface this window configures.
Your account and workspace settings.
# Shortcuts & tray
Desktop keeps Nebula a keystroke away and out of your dock. Summon it with a shortcut, leave it running in the tray, and pull individual threads into windows of their own.
Keyboard shortcuts [#keyboard-shortcuts]
| Action | Default | Scope |
| -------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------ |
| Summon or dismiss Nebula | ⌘ ⇧ Space / Ctrl ⇧ Space | Any app |
| [Quick Send](/docs/desktop/quick-send) | ⌘ \` / Ctrl \` | Any app |
| QuickLive | ⌘ ⇧ C / Ctrl ⇧ C | Any app |
| Mute microphone | ⌘ ⇧ M / Ctrl ⇧ M | Only during a call |
| Settings | ⌘ , | macOS only |
| Quit | ⌘ Q / Ctrl Q | The app |
**QuickLive** is the fastest way onto voice. Press it with no call running and Nebula starts a one-to-one call with you and puts you straight on the mic; press it while a call is already going and it brings that call back up. Press it again to fold the view away.
All four of the top shortcuts are re-recordable in **Settings → Shortcuts**. If the combination you pick is already claimed by another Nebula shortcut, it's refused outright — Nebula keeps your previous one rather than binding a key that quietly does nothing.
**Mute microphone** is the exception to "works from any app": Nebula only claims it while a call is live, so the combination stays free for everything else the rest of the time.
The menu bar icon [#the-menu-bar-icon]
Nebula keeps an icon in your **macOS menu bar** — up at the top of the screen with your other menu extras — so it's reachable whether or not the main window is open. On Windows it's in the notification area at the bottom-right, and on Linux it's in whatever tray your desktop environment provides.
Clicking it opens a short menu:
| Item | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open Nebula** | Brings the main window forward |
| **Quick Send** | Opens the [composer](/docs/desktop/quick-send), same as the hotkey |
| **Settings** | A submenu — **Open Settings…** plus a jump straight to any one section |
| **Check for updates…** | Always here. Updates download on their own, so this is the fast path rather than the only one — it becomes the download and restart control once one is found |
| **Quit Nebula** | Actually exits — see below |
The **Settings** submenu lists all five sections — General, Computer control, Workspaces, Capsule, Shortcuts — so you can land on the one you want instead of opening the window and hunting for it.
If Nebula loses its live connection, a **Live updates disconnected** line appears at the top of the menu so you know the counts have gone stale.
On macOS either mouse button opens the menu. On Windows a left-click jumps straight to Nebula and a right-click opens the menu instead.
What the icon is telling you [#what-the-icon-is-telling-you]
The icon itself carries state, so you can read it without clicking.
Nothing waiting.
Results you haven't read yet. On macOS the count sits next to the icon in the menu bar; on Windows and Linux it's in the tooltip.
An agent is paused waiting on an answer. This outranks unread — if something needs you, that's what the icon shows, however many unread results are stacked up behind it.
Closing versus quitting [#closing-versus-quitting]
Closing the window hides it — Nebula keeps running, agents keep working, and the Capsule stays on screen. Quitting is deliberate: the tray menu, ⌘ Q, or the app menu.
On Linux this depends on your desktop environment running a tray host. Without one there's nowhere for the icon to live, so closing the window quits the app instead.
If you've granted [Computer Control](/docs/desktop/computer-control), quitting also stops agents from reaching your machine — Nebula asks first rather than letting a scheduled job fail quietly.
On macOS, ⌘ Tab to Nebula switches to whichever Space your Nebula window is on and brings it forward, instead of leaving you looking at an empty desktop. Clicking the [Capsule](/docs/desktop/capsule) deliberately doesn't — it's on every Space already, so it keeps you where you are.
Pop-out windows [#pop-out-windows]
Any tab can be pulled into its own window: right-click it in the tab strip and choose **Pop out**. It's useful for watching a long-running job while you work in another channel. Opening the same thing again focuses the window you already have rather than making a second one, and you can keep up to a dozen open at once.
A popped-out window carries just the thing itself — the conversation, with no sidebar and no tab strip around it. Each one is named for what it holds, so a stack of them stays tellable apart when you're cycling windows. Start a conversation before it has a name and the window picks the name up as soon as Nebula titles it.
Clicking a thread in the [Capsule](/docs/desktop/capsule) that belongs to a different workspace opens it this way too, so keeping an eye on one workspace doesn't drag your whole app out of another.
A live call pops out the same way, and it genuinely moves rather than reconnecting from scratch — the call carries on through the handover. It comes back muted, though, so unmute once the window appears. Closing a popped-out call **hides** the window instead of hanging up; you're still on the call.
If **Pop out** is greyed out and says it needs an app update, the shortcut is there but this build's window bridge isn't — update the desktop app.
Related [#related]
Computer name, appearance, and where the hotkeys are set.
What the second shortcut opens.
The corner surface and its own settings.
Install, sign in, and updates.
# Devices
A device is the machine your workspace agents actually run on — where they store files, execute code, control a browser, and host live servers. Every workspace can have one or more devices, and a device can be **virtual** (cloud-hosted) or **local** (your own machine).
Two types of device [#two-types-of-device]
You don't need anyone's permission to connect your own computer — every member can, and the device that appears starts **Private**: nobody else in the workspace can see it or send work to it, not even the person who owns the workspace. You can then [share it with named teammates](/docs/devices/local-device#sharing-your-computer-with-teammates), and only you can — being a workspace admin grants no override. Cloud devices are the shared kind and any member can create one too; what stops you there isn't a permission but the workspace's [Nebula Credits](/docs/settings/workspace#billing--credits-shared) — a cloud machine costs credits to run, so an empty balance is what turns it down.
The [desktop app](/docs/desktop) isn't itself a device — it's how your computer *becomes* one. Installing it and granting [Computer Control](/docs/desktop/computer-control) is what makes your machine a local device agents can use.
Devices vs agents [#devices-vs-agents]
Don't confuse the two:
Think of it as a team of employees (agents) sharing a workstation (the device). Agents bring the intelligence; the device provides the compute.
Adding a device [#adding-a-device]
Open **Devices** in the sidebar and click **New device**. Pick **Virtual** for a cloud machine or **Local** for your own computer.
Cloud-hosted machine with a pre-configured environment. Always on, shared by every agent in the workspace.
Your own computer, made available to agents through the Nebula desktop app. Use your files, your apps, your network.
One device per workspace is marked **Primary** — that's the default agents reach for. You can switch primaries any time from the device card.
Why have both [#why-have-both]
Many workspaces run a virtual device for everything by default. Local devices come in when work *has* to happen on your machine — a private network you VPN into, a folder of files you don't want in the cloud, an IDE or app you've spent years configuring. You can have multiple devices in a workspace and route specific work to a specific one by asking Nebula directly: *"Use my local Mac for this."*
The primary device is what agents reach for when no specific machine is named. Open the device card and click **Make primary** to switch — useful when you add a more powerful virtual device or want your laptop to be the default during the workday.
Open the device card and pick **Remove**. Files on the device stay where they are; for a virtual device, the workspace stops paying for it from that moment forward. For a local device, removal just unpairs your machine — the desktop app stays installed.
A device with agents still attached won't be removed — that's deliberate, so you don't strand an agent with nowhere to run. If the removal fails, check the **Agents** list on the device's Overview tab and either point those agents at another device or delete them, then try again.
Tell Nebula which to use — *"download the file to the virtual device, then copy it to my local Downloads folder"*. Nebula bridges both inside a single task.
Each device card shows a disk-usage bar — used of total, with free space remaining — that turns amber past 75% used and red past 90%. See [virtual device sizes](/docs/devices/virtual-device) to step up to more disk.
Notifications when work finishes [#notifications-when-work-finishes]
When a background task completes, Nebula notifies you in the thread it started in — and optionally pings you on Slack, email, Telegram, or push.
Related [#related]
# Local device
A local device is your own computer, made available to Nebula agents through the desktop app. Use it when work has to happen on your machine — sensitive files, locally installed software, your own dev environment, a network only you can reach.
When to pick local [#when-to-pick-local]
Setting up a local device [#setting-up-a-local-device]
Download the desktop app [#download-the-desktop-app]
Get the Nebula desktop app from [nebula.gg/download](https://www.nebula.gg/download). Available for macOS, Windows, and Linux.
Install and sign in [#install-and-sign-in]
Open the app and sign in by pairing — it shows a short code and confirms it in your browser. See [Nebula Desktop](/docs/desktop) for the full install and sign-in flow.
Turn on Computer Control [#turn-on-computer-control]
Choose how much access to grant, and pick the folder agents work in. This is what actually makes your machine usable by agents — see [Computer Control](/docs/desktop/computer-control) for the choices and what each one unlocks.
Pick which workspace it serves [#pick-which-workspace-it-serves]
Access is granted per workspace, and today a machine serves **one workspace at a time** — registering it again from another workspace moves it there. In the desktop app's **Settings → Workspaces**, switch on the one this computer should be available to.
If you're not sure where a machine currently points, run `nebula-ai local-device status`. It asks the server directly and names the workspace holding it, rather than reporting what this machine last tried to do.
Stay online to use it [#stay-online-to-use-it]
The local device is available whenever the app is running and you're signed in. Quit the app or put the machine to sleep and it goes offline — and a restart doesn't bring it back on its own, so open the app again after rebooting.
Local devices show up on the Devices page with a status dot — green when reachable, grey when the desktop app isn't running. The desktop app also carries a **Computer Control** row at the bottom of its sidebar, telling you whether access is off, on while Nebula is open, or always on.
Prefer the command line, or setting up a machine with no desktop session? The Nebula CLI runs the same helper with `nebula-ai local-device enable`. Whichever one you start it with owns it — the other shows it as managed elsewhere.
What agents can do on your local device [#what-agents-can-do-on-your-local-device]
Read and write files anywhere you grant access. Useful for documents, repos, and media you don't want in the cloud.
Drive native apps you already have — IDEs, design tools, anything scriptable.
Hit internal services, intranet dashboards, and APIs only reachable from your machine.
Use the versions and dependencies you already have set up locally — no fresh container.
Privacy & permissions [#privacy--permissions]
Local devices only see what you explicitly grant, but it's worth knowing what the default actually is. Access starts at **Whole system** — agents can reach anywhere your user account can, and the working folder is only where their commands *start*, not a fence around them. To confine them, open [Computer Control](/docs/desktop/computer-control) and choose **Limit to working folder**. You can also switch access off entirely there at any time.
Your operating system gets involved only for the features that genuinely need it: the microphone the first time you speak on a call, and screen recording the first time you share your screen or use Screen aware. Nebula doesn't ask for accessibility access at all.
When you go offline, the device stops accepting work. Files and credentials stay on your machine; Nebula's cloud never has a copy.
Sharing your computer with teammates [#sharing-your-computer-with-teammates]
Your computer starts **Private** — you are the only person whose agents can reach it. You can hand access to specific teammates from the device's **Access** row, and the choice is always yours to make and yours to undo.
Open **Devices** in the sidebar and select your computer.
In the **Basics** card, find the **Access** row. It reads **Private**, **1 person**, or **N people** depending on who you've added. Select **Manage**.
Under **People with access**, use **Add people** to search your workspace by name. Each person you add gets **Editor** to start; switch them to **Viewer** if you'd rather they only look.
To take access back, remove the person from the same list. It takes effect immediately.
Two limits are deliberate and neither can be configured away:
The person who registered the machine is the only one who can change its access — being a workspace owner or admin grants no override, and a teammate you've given **Editor** still can't pass it on. Everyone else sees the Access row as **View** rather than **Manage**.
**General access** on a local device is locked to **Restricted** — *"Local devices stay private; add specific people above."* There's no setting that opens your computer to the whole workspace; a teammate reaches it only by being named. Cloud devices are the shared kind — that's what a [virtual device](/docs/devices/virtual-device) is for.
Adding anyone changes which credentials Nebula will stage on your machine. While you're the only person who can reach it, your agents can use your [personal connections](/docs/settings/connections) there. The moment someone else can run on it, Nebula falls back to workspace-shared credentials only — for your own runs too, because anyone who can run on the machine could read what's on it. If a job depends on a personal connection, keep that computer to yourself.
The same switch turns off [Claude Code sessions](/docs/tools#working-with-claude-code-sessions-on-your-device) on that machine — starting them and even reading what's running. Nebula can no longer show that the Claude signed in there is yours. If you use both, share a different computer than the one you code on.
Related [#related]
# Virtual device
A virtual device is a cloud-hosted machine that lives in Nebula's infrastructure and stays on around the clock. It comes pre-configured with the tools your agents need — a filesystem, common runtimes, a browser, and the ability to host a live server.
What it can do [#what-it-can-do]
Read, write, and organize files that persist between conversations. Everyone in the workspace sees the same filesystem; everyone's work lands in the same place.
Run Python, Bash, or TypeScript with real package managers. Common data libraries like pandas, numpy, matplotlib, and requests come pre-installed.
Control a full browser to interact with websites and web apps — fill forms, click buttons, extract data, log in to dashboards.
Spin up a web server, get a public URL, and share it for review or testing. Useful for prototypes, previews, and internal tools.
Always on [#always-on]
A virtual device runs continuously. It doesn't sleep between conversations, doesn't reset when someone closes the app, and doesn't lose state when members switch devices of their own.
What it makes possible [#what-it-makes-possible]
Kick off a scrape, leave it for hours, come back to the results. The device keeps running.
Download → process → store → query. State lives between conversations.
Install your own scripts and binaries. Agents in the workspace can use them in any thread or automation.
Upload a file in one thread; another agent in another thread can read it from the same filesystem.
Build a test site or app and get a real URL to share with teammates for feedback.
Multiple agents share the same files, reading each other's outputs without manual passing.
Adding a virtual device [#adding-a-virtual-device]
Open
**Devices**
from the sidebar and click
**New device**
.
Pick
**Virtual Device**
in the create dialog and select
**Continue**
.
Pick a size (CPU / RAM / disk) and a name. Nebula provisions the device and brings it online in seconds.
The device shows up on the Devices page with a green status dot when it's ready.
One device per workspace is marked **Primary** — agents reach for it by default. The first virtual device you create becomes the primary; you can switch later from any device card.
Creating a virtual device is an admin job. If you're not a workspace admin the **Virtual Device** tile reads **Admins only** and won't open — ask an admin to make one, or [connect your own machine](/docs/devices/local-device) instead, which any member can do.
Choosing a size [#choosing-a-size]
Pick a size when you create the device, and upgrade later from the device card as your work grows. The card and detail page show the active size and its specs.
| Size | CPU | RAM | Disk |
| ---------- | ----- | ----- | ------ |
| **Small** | 2 CPU | 8 GB | 40 GB |
| **Medium** | 4 CPU | 16 GB | 250 GB |
Small handles everyday research, writing, and light scripting. Step up to Medium for heavier data work, larger files, or several agents working in parallel.
Watching disk usage [#watching-disk-usage]
The device card and the detail page show a disk-usage bar — **used of total, with free space remaining** — that turns amber past **75%** used and red past **90%**. The bar appears once the device reports its first reading.
Running low? Ask Nebula to clear out files you no longer need, or upgrade the device to a larger size.
Related [#related]
# Home and navigation
Home is where you start work: type what you need, or talk it through out loud. Everything else in Nebula hangs off the sidebar on the left, and whatever you open from there stays with you as a tab.
Start anything from Home [#start-anything-from-home]
Home is deliberately empty. There's the Nebula mark and one box — nothing to read, nothing to triage. Type a request and send it: Nebula creates a thread, works out which agent should handle it, and takes you there. The mark itself is how you start a call instead.
The box reads **Ask Nebula anything** — or your orchestrator's name, if you've renamed it. Send a request and Nebula routes it to the right agent; you don't pick one.
The Nebula mark above the box is a button — it reads **Talk to Nebula** (or your orchestrator's name) and starts a [live session](/docs/live) right there, for when explaining is faster than typing. It says **Starting call…** while it connects.
Send a task and carry on. The thread keeps running, shows up in the sidebar, and tells you when it needs you. To attach files, drag them anywhere onto the page — not just onto the box — and it dims with **Drop files to attach** while you're over it. They upload as soon as you let go, so they're ready before you finish typing. Files go up to 100 MB each, and anything larger is called out by name.
The toggles under the box [#the-toggles-under-the-box]
These controls sit beneath the box, and they apply to the thread you're about to start.
| Control | What it does |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flash** / **Max** / **Ultra** | Picks the [Nebula tier](/docs/models) the request runs on, from quickest to deepest. It appears when you're on a Nebula model. Chosen here, it rides into the next thread you start and then clears. |
| **Workspace** / **Private** | Sets who can see the new thread. New threads start **Private** — yours alone until you say otherwise — and switching to **Workspace** shows it to everyone. |
| **Safety gate** | A shield to the left of the paperclip, reading **Safety gate: on** or **off**. On, agents pause for your approval before risky actions — see [Approvals](/docs/settings/approvals). |
Find your way around [#find-your-way-around]
The sidebar is the map. Every destination in Nebula is one row, and the row you're on is highlighted.
| Row | What's there |
| ----------------- | --------------------------------------------------------------------------------------- |
| **Home** | This screen — the launcher. |
| **Notifications** | Your [inbox](/docs/notifications), with a count of what's unread. |
| **Agents** | Every [agent](/docs/agents) in the workspace. A dot appears when one has something new. |
| **Jobs** | Scheduled and triggered work — see [Jobs](/docs/jobs). |
| **Miniapps** | The [miniapps](/docs/miniapps/using) you've built. |
| **Live** | Sessions, past and present. A blue dot pulses while a call is running. |
| **Devices** | The [machines](/docs/devices) your agents can use. |
Directly beneath the nav sits **Pinned** — the things you keep coming back to. It holds more than threads: pin an **agent**, a **job**, a **mini app**, or a **device** from its own page and it lands here too, grouped by kind with threads first. Drag a thread up into Pinned to keep it there; with nothing pinned yet, starting a drag makes the lane appear as a **Drop here to pin** target. Hovering any row reveals a single **×** that unpins, archives, or quietly clears it until there's new activity.
Then **Channels**, collapsed until you open it. While it's closed the label carries a count — **Channels (7)** — and a badge for how many have something unread; open it and the count goes away, because the rows are the count. Sort them by **Name**, **Recent**, or **Unread** from the control on the right of that row.
Last comes **Threads**, what's been active lately. It collapses the same way Channels does, folding away behind **Threads (12)**. The two start from opposite places: Threads is open when you arrive, Channels is closed. **Pinned** isn't collapsible.
Its header also carries a filter for **what kind** of thread you want to see — **Jobs**, **Miniapps**, **Agent DMs**, and **Channels**, all shown by default. Turn any of them off and the lane says so with a small dot on the filter; **Show all types** brings them back.
Pinned threads follow your account, so a thread you pin on your laptop is pinned in the desktop app too. The rest of the sidebar's arrangement — which lanes are open, the order you dragged your pins into, which thread types you've hidden, and pinned agents, jobs, mini apps and devices — is remembered per browser rather than travelling with you.
Every live call, not just yours [#every-live-call-not-just-yours]
Under the **Live** row hangs one entry per [call](/docs/live) running in the workspace right now — not only the one you're on. Each shows who's in it as a small stack of faces, the call's title, and a timer counting up, so you can see something is happening and join it without waiting for an invite.
You'll see any call in a channel the whole workspace can reach. Calls in private channels stay hidden unless you're already in them. Entries appear as calls start and vanish as they end, and the **Live** row itself carries a pulsing blue dot whenever there's at least one.
Your own call gets one more behaviour: while you're on it, it steps out of the **Threads** lane, so it's in the Live list and nowhere else rather than in two places at once.
Press ⌘B to collapse the sidebar to a narrow icon rail, and again to bring it back. You can also drag its right edge to resize it. Hovering the collapsed rail peeks it open without pushing the page around. The rail keeps the nav rows and drops the pinned, channel, and thread lanes, so it stays a way to navigate rather than a cramped version of everything.
At the very bottom are the two things you always want in reach: **Search** (or ⌘K — see [Search](/docs/home/search)), and your account, where **Profile**, **Workspace settings**, and **Sign out** live. Settings is never in the nav list itself; it's always in that account menu.
Just above those, one card at a time offers whatever's most useful next — the [Getting started checklist](/docs/getting-started/quickstart#the-getting-started-checklist) in a new workspace, later an invite prompt or a nudge to install the desktop app. Dismiss any of them with its **×** and it stays dismissed.
Tabs keep your work open [#tabs-keep-your-work-open]
Above the page, a strip holds everything you've opened. Tabs open by themselves — visiting an agent, a channel, a job, a miniapp or a call leaves one behind, so going somewhere else doesn't lose your place. There's no "new tab" button, and you never have to open a tab before you can use one: go somewhere and the tab is already there.
Threads, calls, channels, jobs, agents, miniapps, and section pages like Agents or Devices. Home is the exception — it's the no-tab state, so the strip sits empty behind it.
Click the **×**, middle-click the tab, or press ⌘W. Right-click for **Close**, **Close others**, **Close to right**, and **Pop out**. Nebula keeps up to ten tabs per workspace and drops the least recently used when you go past that.
⌘1 through ⌘9 jump straight to a tab, and ⌘0 goes Home. To step through them in order, use the left and right arrow keys, h and l, or ⌥← and ⌥→. Those all stand down while you're typing — ⌘⇧\[ and ⌘⇧] keep working even mid-sentence.
Clicking a tab drops your cursor straight into whatever you'd type there; stepping through with the keyboard deliberately leaves focus alone. Esc lets go of the composer, and pressing it again closes the tab.
A pulsing blue dot means an agent is working in there; amber means it wants your input or has unread messages. Hover a tab for its title, where it lives, and the last message.
Your tabs persist — close the browser and they're waiting when you come back. They're kept per workspace, so switching workspaces gives you that workspace's tabs, not a merged pile.
Tabs and the Threads lane aren't the same list [#tabs-and-the-threads-lane-arent-the-same-list]
They look alike on purpose — a thread carries the same icon in the sidebar that it carries in its tab — but they answer different questions, and it's worth knowing which one you're looking at.
So closing a tab doesn't remove anything from the sidebar, and a thread can sit in the lane having never been open in this browser at all.
Closing the tab of a call you're on asks first: **Leave this call?** — *"Closing the tab disconnects you. The call carries on for everyone else on it."* Choose **Leave call** or **Stay on the call**.
Related [#related]
# Search your workspace
Search jumps you to any conversation, message, agent, job, miniapp, or file in your current workspace, and runs common actions besides. It's the fastest way to find a conversation you half-remember or an agent you set up months ago.
Open it from the **Search** row at the bottom of the sidebar — or press ⌘K (Mac) / Ctrl K (Windows / Linux).
What you can search [#what-you-can-search]
Match against thread titles and auto-summaries.
The words inside conversations, so you can search for a phrase you remember rather than the title around it.
Find an agent by name. Open the result to start a DM or see what it does.
Scheduled and triggered work by name — see [Jobs](/docs/jobs).
Search by app name. Click to launch the app right from results.
Anything uploaded into the workspace — channel attachments and thread files.
Search is always scoped to your active workspace. Switch workspaces from the top of the sidebar to search a different one.
How matching works [#how-matching-works]
Search ranks results by how well they match first, and falls back on recency to break ties — so a phrase you typed months ago still surfaces above a loose match from yesterday. Thread matches consider the auto-generated title and the summary; message matches look inside the conversations themselves; agent and job matches use names and descriptions; miniapp matches use the app's display name; file matches look at filenames and attached metadata.
Message search reaches back six months. Anything older is still in the thread — open it and scroll, or ask Nebula to dig it out for you, which isn't bound by that window.
What people said out loud on a [call](/docs/live) doesn't come back in message results. Ask Nebula about it instead — it can search call transcripts even though ⌘K doesn't.
Results don't leak across workspaces. Switching workspace from the top of the sidebar re-scopes search to whatever you switched to.
Tips [#tips]
Open it without typing anything and you get where you've just been, a **Quick actions** list — **New channel**, **Create agent**, **Message Nebula**, and a light/dark switch — and a **Go to** list covering every destination in the sidebar. It's the fastest route to most things, not only to things you've already made.
Use arrow keys to highlight a result and Enter to jump in. Search closes on selection.
Related [#related]
# Your first agent
An agent is an AI worker tuned for one job — research, monitoring, reminders, project management. Creating one takes about a minute with the **Create agent** button on the Agents page.
Opening the wizard [#opening-the-wizard]
Open **Agents** from the sidebar and click **Create agent**.
The Create Agent wizard opens. Step through the five pages.
Prefer to skip the wizard? Just tell Nebula what you want — *"create an agent that tracks GitHub issues for me"* — and it'll build the agent and walk you through any setup.
Or just ask Nebula [#or-just-ask-nebula]
The fastest way is to skip the wizard entirely and describe the agent in chat.
The five steps [#the-five-steps]
Pick a **name** (e.g. *Research Assistant*, *Standup Bot*) and optionally an **image** and **model**. The default model is usually right; pin one only if this agent needs a specific capability. See [agent configuration](/docs/agents/configure) for model tradeoffs.
A short summary of what the agent does. Nebula uses this when routing tasks — if you ask Nebula to "ping the standup bot", the description is how it knows which agent to pick.
Pick the toolkits and services the agent can act on — Slack, GitHub, web search, and the rest. Optional, and you can add or remove tools anytime from the agent's [details panel](/docs/agents/configure).
Decide who can use the agent: set **general access** for the workspace (none, read, or write), invite specific **people**, and choose a **device** — leave it on *Automatic* to run in the cloud, or pin a specific one. See [scoping & access](/docs/getting-started/sharing-and-access).
A read-back of everything you set — identity, description, tools, access, and device — each with a jump-back link to edit. Looks right? Click **Create agent**.
After it's created [#after-its-created]
The agent shows up on the **Agents** page, and it joins your [roster](/docs/agents/roster) straight away — so Nebula can start handing it work without you doing anything else. Anyone in the workspace can see it and mention it. To make changes — instructions, tools, memory — click the agent to open its [configuration page](/docs/agents/configure).
Try this for your first agent [#try-this-for-your-first-agent]
*"A research assistant that summarizes articles and cites sources."*
*"A code reviewer that checks our PRs for bugs and suggests improvements."*
*"A news monitor that watches our industry and posts a digest every weekday at 9am."*
*"A meeting prepper that pulls together notes, attendees, and recent activity 30 minutes before each meeting."*
Need help? Ask Nebula directly in chat first — it can answer most questions and even reconfigure the agent for you. For bugs or anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# Your first channel
A channel is a topic-based room your whole workspace can use. Inside it, conversations split into threads, each with its own context and an auto-generated summary.
Opening the modal [#opening-the-modal]
Open the command palette with **⌘K** and choose **Create channel** — or just ask Nebula in chat (below).
Give the channel a name. Nebula slugs it for you — *"Project Planning"* becomes .
Pick a visibility (see below), then **Next** to add members or agents.
Or create one in chat [#or-create-one-in-chat]
Workspace vs Private [#workspace-vs-private]
Pick **Workspace** unless you specifically need privacy. Discoverability is a feature — most channels benefit from being open to whoever is curious.
What happens after you create one [#what-happens-after-you-create-one]
The channel joins the **Channels** lane in your sidebar, and it shows up in search. Anyone with access can open it to see the thread list. Use the composer at the top of that list to begin the first conversation — Nebula will auto-title and summarize as messages come in.
See [Channels & threads](/docs/channels) for the channel layout and [Threads](/docs/channels/threads) for how threads work.
Channel names that age well [#channel-names-that-age-well]
`q3-launch-prep` beats `marketing`. Specific names tell teammates what belongs there.
Slack convention. Easier to read and Nebula slugs them this way by default.
`2026-onsite`, `q1-planning` — gives the channel a natural archive point.
Long names truncate in lists and filter tags. Aim for under 25 characters.
Need help? Ask Nebula directly in chat — it can create, rename, and invite members to channels for you. For bugs or anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# Your first miniapp
You can create a miniapp — a dashboard, form, or picker — by describing it to Nebula in plain English. Nebula builds and deploys the interactive tool for your workspace, no code required.
Opening the modal [#opening-the-modal]
Open **Miniapps** from the sidebar and click **Create miniapp**.
Pick which agent should build it — is fine for most cases. Specialist agents (with their own connected tools) sometimes do better.
Describe what you want in the textarea. One or two sentences is usually enough.
Hit send. Nebula builds, deploys, and adds the app to the **Miniapps** page.
Or describe one in chat [#or-describe-one-in-chat]
Examples that work well [#examples-that-work-well]
*"A dashboard that shows my daily GitHub stats — PRs opened, PRs merged, lines changed — for the last two weeks."*
*"A meal picker the family can vote on. Three options. Votes lock at 6pm Friday."*
*"A form to collect graduation party RSVPs with name, plus-ones, and meal choice. Submissions land in a Google Sheet."*
*"An interactive solar system lesson where students click planets to see orbits and compare sizes."*
What good descriptions have [#what-good-descriptions-have]
"Show daily GitHub stats" beats "track GitHub". Tell Nebula what to render.
Sliders, votes, filters — say what users should be able to do, not just see.
"Pull from our Stripe account" or "from this CSV I'll upload" gives Nebula a starting point.
"Three options", "stacked bars", "side-by-side" — quick guardrails save iterations later.
After it's built [#after-its-built]
The app shows up on the **Miniapps** page. Anyone in the workspace can open and use it. To iterate, drop back into the channel where you created it and ask for changes — *"swap the pie chart for stacked bars"* — Nebula will rebuild and redeploy.
See [Miniapps](/docs/miniapps/using) for opening, navigating, and removing apps.
Stuck on what to ask for? Ask Nebula to help you draft the mini-app description first. For unresolved issues, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# What is Nebula?
Nebula is a workspace where you and your team work with AI agents. Tell Nebula what you need — research, writing, code, posting to Slack — and the right agents take it on. When you're ready, make it run on autopilot.
You don't need to write code or configure anything upfront. Just open a workspace and start talking.
The shape of a workspace [#the-shape-of-a-workspace]
A launcher for starting anything, with the sidebar holding every destination and the work you have open.
AI workers shared across your workspace. Every member sees and uses them.
Topic-based rooms with auto-summarized threads for each conversation.
Dashboards, forms, and pickers Nebula builds for your team on request.
Cloud machine with a filesystem, code execution, and a browser. Always on.
Schedule recurring work or react to events from connected apps.
What can you do with Nebula? [#what-can-you-do-with-nebula]
**Ask it to research.** *"Find the top 3 trending AI papers this week and summarize them."*
**Run code.** *"Analyze this CSV and chart monthly revenue."*
**Automate recurring work.** *"Every weekday at 9 AM, post an AI news digest to in Slack."*
**Connect to your apps.** Native bots for Slack, Discord, Telegram, Twitter — plus 4,000+ services via OAuth. See [Connecting apps](/docs/tools).
Next steps [#next-steps]
Stuck? Just ask Nebula — it can answer questions about itself and even configure things for you. For bugs or feature requests, email [support@nebula.gg](mailto:support@nebula.gg).
# Quickstart
You'll have a working workspace and your first creation up in a few minutes. Sign up, say hi, and Nebula walks you through what to do next.
Sign up [#sign-up]
Go to [nebula.gg](https://nebula.gg) and continue with Google, or enter your email and verify with the code Nebula sends you. Your account opens straight into a personal workspace — no setup screens to click through.
Meet your Nebula [#meet-your-nebula]
On first run, Nebula introduces itself — and you can make it yours. Give your personal orchestrator a name (it defaults to **Nebula**) so it feels like *your* assistant. Every member gets their own; see [Your own Nebula](/docs/agents#your-own-nebula).
Connect your apps [#connect-your-apps]
Right after your workspace is created, Nebula offers a grid of apps to connect — Slack, Gmail, GitHub, and 4,000+ more — so your agents can act on real systems from day one. Skip it and connect later anytime; Nebula also prompts you in chat the moment an app is needed. See [Tools](/docs/tools).
Meet your workspace [#meet-your-workspace]
Signing up drops you straight into a conversation rather than an empty screen. You land in a thread called **Welcome to Nebula** in your `#general` channel, opened with a note built from what you told Nebula on the way in — so it already knows what you're here to do. Nebula replies with one concrete first task worth trying.
Answer in plain English. Replying with something like *"create an agent that tracks GitHub issues for me"* kicks Nebula off — it'll walk you through the rest. Or pick one of the next pages and do it manually.
A **Your workspace is ready** card sits in the sidebar while you find your feet. Everything you set up during signup is already in that thread, so replying there is the fastest way to start.
Make your first thing [#make-your-first-thing]
A dedicated AI worker for one job — research, reminders, monitoring, anything.
A topic-based room your whole workspace shares.
A dashboard, form, or picker Nebula builds from a description.
Invite your team [#invite-your-team]
Personal workspaces are full Nebula. The moment you invite someone, it's a team workspace — same surface, just with more people.
See [Members & roles](/docs/settings/members) for the invite flow.
Try these prompts next [#try-these-prompts-next]
A few high-value asks once your workspace is set up:
"Summarize the last 24 hours of messages in on Slack."
"Find every open GitHub issue labeled `bug` and rank them by age."
"Every Monday at 9am, search industry news and post a digest to ."
"Create an agent that monitors Twitter for mentions of our brand."
Stuck? Ask Nebula directly — it can answer questions about itself and configure things for you. For bugs or feature requests, email [support@nebula.gg](mailto:support@nebula.gg).
The Getting started checklist [#the-getting-started-checklist]
Nebula tracks the same ground this page covers, down at the bottom of the sidebar. The card reads **Getting started** with a count — *2 of 4 complete* — and each row takes you where you need to go.
| Step | Counts as done when |
| --------------------------- | ------------------------------------- |
| **Create your first agent** | The workspace has an agent you made |
| **Send your first message** | Any channel has activity in it |
| **Connect a tool** | You've connected at least one account |
| **Invite a teammate** | Someone else has joined the workspace |
Finished steps go struck through, and the card retires itself once all four are done. Dismiss it with the **×** if you'd rather not see it — that sticks, including across signing out and back in.
That footer spot shows one nudge at a time, so the checklist shares it with things like an invite prompt or the desktop app suggestion. If it isn't showing, something else has the slot.
Related [#related]
# Sharing & access
You can share any agent, job, or miniapp with your workspace and set exactly who gets to open it and who gets to change it — all from one **Access** dialog. Connections stay personal, so a shared agent always acts through its owner's connected apps.
Every agent, job, and miniapp has an **Access** row with a **Manage** button (you'll see **View** instead if you only have view access). Open it to set two things: the **general access** level for the whole workspace, and named **people** with their own view-or-edit grant.
Set general access [#set-general-access]
General access decides what everyone in the workspace can do with the item, before you grant anyone individual access.
You pick a general access level when you create an agent, job, or miniapp, and you can change it anytime from the Access dialog.
A restricted agent isn't stuck in your own conversations — you can bring it into a shared channel and use it there. What access controls is *who else* sees it: to anyone without access it doesn't appear in that channel's agent list, isn't offered as somewhere to hand work, and won't resolve if they try to mention it.
Grant specific people [#grant-specific-people]
Below general access is a people list. Add a teammate and choose their level — the same two levels apply whether the item is Restricted or open to the whole workspace.
Can open and use the item — chat with the agent, run the job, launch the miniapp — but can't change how it's built or who else has access.
Can do everything a viewer can, plus edit the item, delete it, and manage its access.
The person who created an item is always an **Editor** and can't be removed — someone always owns it. A member's effective access is the higher of the general access level and any grant you give them by name.
Your connections belong to you [#your-connections-belong-to-you]
When you connect an app — Gmail, Slack, GitHub, and so on — that connection is tied to **your** account, not to the workspace as a whole.
On the **Settings → Accounts** page you only ever see the connections **you** set up. You won't see a teammate's connected accounts, and they won't see yours.
Connecting an app authorizes Nebula to act as **you** in that app. That's why connections stay personal — each person grants their own access.
Pick which account an agent uses [#pick-which-account-an-agent-uses]
Connecting an app in Settings makes it available to you. It does **not** hand it to your agents. Each agent gets the accounts you choose for it, one toolkit at a time, so an agent never quietly spends an identity you didn't mean it to.
Open the agent, go to the **Tools** tab, and find the **Accounts** section. A toolkit with nothing chosen yet reads **Choose account**; pick from the list, or use **Connect new account** to add one on the spot. You can select more than one account for the same app.
This is why an agent with a connected app can still ask to connect. If you never chose the account, the agent has the *tool* but no *identity* to run it as.
You don't have to do this up front. An agent with an unchosen account runs normally until it actually needs that app, then puts a connection card in the chat — **Or use a connection you've already set up:** — where you pick an existing account and hit **Use this connection**. Choosing it there is the same as choosing it in the Tools tab, and it sticks.
You can also just say it:
Only the agent's **owner** can make this choice, in chat or in the Tools tab, because the account being spent is theirs. If you ask about someone else's agent, Nebula tells you to ask them instead.
Some accounts are shared with the whole workspace, and Nebula labels those when it offers them. Picking one means *everyone* who runs that agent acts as that identity — worth a thought before you choose it.
Picking the wrong one is now an error rather than a silent substitution. If you name an account that isn't connected, Nebula tells you which accounts *are* available instead of quietly running as a different one.
What happens when you share an agent [#what-happens-when-you-share-an-agent]
Here's the part that surprises people: a shared agent always runs with **its owner's** connections, no matter who starts it.
You build an agent,
**choose your Gmail account for it**
in the Tools tab, and give it workspace access.
A teammate opens the agent and asks it to send an email.
The agent sends that email through
**your**
Gmail connection — because the connection belongs to you, the owner.
So sharing an agent shares the *capability*, and the work flows through the owner's connected accounts. Keep an agent restricted if you'd rather its access stay with you alone.
That first step is load-bearing. Only the owner can attach an account, so if you share an agent without choosing one, a teammate who uses it gets told the owner has to connect that app first — the agent won't fall back to their credentials or to another of yours.
A teammate can't repair it from their side. The agent's account belongs to the owner, so the owner reconnects the app or chooses a different account for that agent. Until then, teammates see a message saying the connection belongs to another member.
Two people, two Gmails [#two-people-two-gmails]
Because connections are personal, two teammates connecting the same app create **two separate connections** — and effectively two separate agents.
Each connection is granted by an individual person and acts as that person. Ada's Gmail and Bo's Gmail are distinct connections, so an agent Ada owns uses Ada's Gmail and an agent Bo owns uses Bo's Gmail — never a mix.
You each connect your own Gmail and own your own agent (or your own copy). They can both live in the same workspace; they simply act through different accounts.
Only through an agent you own and share. They can run your workspace agent — which uses your connection under the hood — but they can't see or borrow the raw connection itself.
Not sure who can see what? Ask Nebula in chat — it can tell you an item's access and which connections an agent uses. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# What Nebula can do
Nebula is a general-purpose AI agent that can research, write, code, and take actions across your connected apps. Here's a clear breakdown of what it handles today and where its limits are.
Research and information [#research-and-information]
You can ask Nebula to find, read, and summarize information from across the web.
Search the web for current information on any topic.
Read and summarize articles, PDFs, and web pages.
Compare products, pricing, and competitors side by side.
Fact-check claims against multiple sources.
Writing and content [#writing-and-content]
Nebula writes, edits, and rewrites content in any format or tone.
Blog posts, emails, and social media threads.
Technical documentation and reports.
Adjust tone, length, or audience for existing content.
Translate between languages.
Code and data analysis [#code-and-data-analysis]
Your agent writes and runs Python, Bash, and TypeScript on your [Device](/docs/devices) with data science libraries pre-installed.
Analyze CSVs and spreadsheets with pre-installed data science libraries.
Generate charts and visualizations from your data.
Write and debug scripts in Python, Bash, and TypeScript.
Process and transform data into the formats you need.
App actions [#app-actions]
When you [connect an app](/docs/tools), Nebula can interact with it directly.
Read channels, send messages, and post summaries.
Send messages and monitor channels.
Post tweets, search mentions, and draft replies.
Send messages and create polls.
List issues and PRs, triage, and comment.
Read, compose, and send emails.
Connect via [Integrations](/docs/tools) using OAuth.
Automation [#automation]
Nebula can run tasks on a schedule or in response to events — no code needed.
Schedule recurring tasks on a daily, weekly, or custom cron cadence.
Trigger actions from events — a new Slack message, GitHub issue, or webhook.
Chain multiple steps together into a single automated workflow.
Media [#media]
Nebula can generate and process images, audio, and other media.
Generate images from text descriptions.
Transcribe audio recordings into text.
Convert text to spoken audio.
Process and describe images.
Browser [#browser]
Nebula can open browser sessions to interact with websites that don't have APIs.
Log into authenticated sites with 1Password integration.
Fill out forms, click buttons, and extract data from web pages.
Navigate multi-step web workflows end to end.
Collaboration between agents [#collaboration-between-agents]
Multiple agents can work together on a single request. Nebula splits the work across the specialists on its [roster](/docs/agents/roster) — and you can always name an agent yourself by mentioning it.
Related [#related]
# Live camera
Turn on your camera in a call and your agent can see what you show it. Hold up a router, a receipt, a whiteboard, or a part number, and ask about it directly.
Turning it on [#turning-it-on]
The **camera** control sits in the controls bar alongside your mic and speaker. While your camera is off it's a single button listing the cameras Nebula can see — pick one and you're live. Before you've granted camera permission that list is empty and reads *"No cameras detected yet. Start the camera to grant access. You can switch devices once it's on."* — start it once and your devices appear. Once you're on, the icon turns it back off and the caret opens **Video settings**, where you can switch camera or change quality against a live preview of yourself.
| Quality | Resolution | Best for |
| -------- | ---------- | -------------------------------------- |
| Low | 320 × 240 | The lightest option — slow connections |
| Standard | 640 × 480 | Balanced, and the default |
| HD | 1280 × 720 | Sharpest — showing detail |
**Video settings** gives you a live preview *before* you go on, so you can check your framing while the camera is still off. Whatever you pick sticks as the default for your next call.
Your own video comes back to you mirrored and labelled **You**, and anyone with a camera on picks up a **Video** badge on their tile. Cameras share the stage with screenshares — one is focused at a time, with the rest as thumbnails.
Letting your agent see you [#letting-your-agent-see-you]
Your agent looks through your camera the same way it looks at a shared screen: **when you ask**, not continuously.
It reads the camera of **whoever is speaking**, so "can you see this?" always means yours — you never have to name a camera. It only sees people whose own camera is on, and if yours is off it'll ask you to turn it on rather than guess at what you meant.
What it's good for [#what-its-good-for]
Model numbers, serial plates, error codes on a device, a label too small to type out. Hold it up and ask.
A whiteboard, a rack of equipment, a room you're describing. Easier to point a camera at than to write down.
If your hands are busy, talking and showing beats stopping to type — the agent takes a look each time you ask.
Camera and screen share aren't either/or. Share your screen for what's on the computer and switch the camera on for what's in front of you — the stage handles both, focusing one at a time.
Permissions [#permissions]
The first time you turn the camera on, your operating system asks for camera access. It's the standard prompt, and you can change it later in your system's privacy settings.
Related [#related]
Show your agent what's on your computer instead.
The stage, the rail, and the work board.
Pick a voice, and set your mic and speaker.
Starting a call and who's on it.
# Inside a call
Inside a call you talk, show things, and watch work land — all in the same room. The stage reflows around whatever matters most at that moment, so you rarely have to arrange anything yourself.
The stage [#the-stage]
Everyone on the call sits on an orbit ring, and the call's one agent sits there too, in its own place. There's no sidekick avatar pinned to whoever started the call. A face that's unmuted carries a green mic badge and a live meter under it; a muted one goes grey and still.
Four controls run the room, always in the same order — **mic**, **speaker**, **camera**, and **share**. Each is a split control: the toggle turns it on or off, and the caret beside it picks the device or quality. **Leave** is the outlined red circle at the end of the call header. On a phone the four controls move to a bar along the bottom, and Leave moves down there with them.
The speaker toggle is the one worth knowing. It mutes **the agent**, and only in your ear — everyone else on the call stays audible to you, and they keep hearing the agent normally.
The room reshapes around how you're talking [#the-room-reshapes-around-how-youre-talking]
There's no mode switch to find. The layout follows what you've muted.
With your mic or the agent's voice live, the people fill the room. This is the default when you start a call.
Mute both your mic and the agent, and the call becomes a written one: the conversation moves into the middle at reading size, the people compact above it, and you get a roomier box to type in. Unmute either one and it's a spoken call again.
A screenshare, your camera, or a thread you've pulled up takes the stage, and the people step aside into a strip. They coexist — start a screenshare while your camera is on and both stay up, with whatever you're focused on filling the space.
Because the layout is just a consequence of muting, there's nothing to turn back on afterwards — unmuting is the way out. Your camera and screenshare keep working whichever way you're talking.
Active and background agents [#active-and-background-agents]
An agent on a call sits in one of two postures, and you can flip it between them at any point without interrupting the conversation.
**Active** reads the room instead of making you manage it. On your own with an agent it answers every turn, which is what you want when you're thinking out loud. Add other people and the same posture holds back on its own — it stays out while you and your teammates work something through, and speaks up when the conversation turns to it. You don't have to summon it formally: its name or a [wake word](/docs/live/voices#wake-words) always works, but simply talking to it is usually enough. When it can't tell whether a question was meant for it or for the person next to you, it stays quiet rather than talking over anyone. Nothing to switch when the group grows, and nothing to switch back when it shrinks.
**Background** is a hard mute. The agent keeps listening and keeps doing the work you hand it, but it won't say a word out loud — not even when you call it by name. Anything it has to tell you lands as text in the chat rail instead. Reach for it when you want an agent on the job without a voice in the room.
To change a posture, click the agent's tile — it toggles between the two.
You rarely need to touch this in a group call — an active agent already stays out of the way until someone addresses it. Switch to background when you want it working with no voice at all.
There are two ways to quiet an agent, and they differ in who they apply to.
What the tile is telling you [#what-the-tile-is-telling-you]
Beyond the posture, a tile shows what its agent is doing right now.
| State | Meaning |
| --------------- | ------------------------------------------------------------------ |
| **Listening** | It's here and attending the room, waiting for something to do |
| **Speaking** | It's talking right now |
| **Working** | It's running a tool for you |
| **Dispatching** | It's handing work to a specialist; watch for a card under **Work** |
The tile carries this without words — each state has its own motion, and speaking is simply the same ring moving faster. **Listening** is where it rests between turns, so a calm ring means it's there and waiting rather than idle. An agent that has dropped off the call shows no ring at all. There is deliberately no "thinking" state: you see it listening, then you see it working.
If a call loses its connection, the agent's state **freezes** where it was rather than flipping to something new. A ring that stops moving is the signal that the room dropped, not that the agent changed its mind.
Asking about your workspace [#asking-about-your-workspace]
Not everything you say needs to become work. Ask about something that already exists in your workspace and your agent just answers, out loud, in the same breath — no thread, no hand-off, no waiting.
It can look across threads, agents, jobs, and miniapps this way. The dividing line is knowing versus doing: questions get answered on the call, and only genuinely new work gets dispatched to a specialist. When it does dispatch something you asked for, it says so — a quick "on it" — rather than going silent while you wonder whether it heard you.
Your teammates' and agents' names are fed to the transcriber before the call starts, so unusual names come out spelled right instead of turning into something phonetically close.
Bringing someone else in [#bringing-someone-else-in]
If you realise mid-call that you need someone, just say so — your agent can pull a teammate in by name without you leaving the room.
Your agent matches the name against your workspace directory, so a first name is usually enough. If two people could match, it asks which one you meant before inviting anyone. Because inviting reaches outside the room, your agent says out loud what it did rather than doing it silently.
The invite arrives as a notification that opens the live call when clicked — it doesn't ring anyone. Someone already on the call won't be pinged again. You can also invite from the call's own invite dialog if you'd rather pick people from a list.
Showing your agent something [#showing-your-agent-something]
Two ways to put something in front of your agent mid-call, each with a page of its own.
Show what's on your computer — a dashboard, an error, a document — and ask what it says.
Turn on your webcam and hold something up. Good for labels, hardware, and whiteboards.
Either one takes the stage, compacting the people into a strip beside it. In both cases your agent looks **when you ask** rather than watching continuously, and answers in the same turn.
Screenshares, cameras, and pulled-up threads all share the same stage, so they don't cancel each other out. Whatever you're focused on fills it and the rest wait as thumbnails you can switch between.
Putting a thread on screen [#putting-a-thread-on-screen]
It works the other way too. Ask your agent to pull up a thread and it puts that thread on the stage for everyone — no screen sharing, no hunting for a link.
The thread appears as a shared screen with a chip saying who's sharing it, showing the conversation and any files in it — stripped of the activity chrome so it reads cleanly from across a room. One thread at a time: pull up another and it takes the place of the first.
Pulling a thread up shows it to **everyone on the call**, and closing it puts it away for everyone too — it isn't a private view. Anyone without access to that thread sees a note that it's been pulled up rather than its contents, so permissions still hold.
Say **put that away** to clear the stage, or use the X on the shared screen. Starting a screenshare or camera doesn't push the thread off — both sit on the stage together, and you pick which one has the floor.
The work board [#the-work-board]
When you and your agent agree on something to do, it dispatches the work to a specialist and a card appears under **Work** in the rail, with a count on the tab so you can see it land without looking away from the room.
Each card carries the same statuses you see elsewhere: **live** while it's working, **unread** once a result is waiting, then read. You can cancel, mark read, or archive without leaving the call. Until something is dispatched the tab isn't there at all, and an empty board reads *"Ask for something and the dispatched threads land here."*
Keeping an eye on something [#keeping-an-eye-on-something]
Some things you want checked repeatedly rather than answered once. Ask your agent to watch for something and it sets up a **watch** — a recurring check that runs quietly in the background of the call and speaks up only when there's something to report.
You set watches by asking — there's no form to fill in. Your agent can watch a **thread**, a **search** across your workspace, your **jobs**, your **shared screen**, or your **camera**. You can run up to five at once, and at most two of those can be watching your screen or camera. One-off reminders — *"nudge me in twenty minutes"* — are counted separately, so setting a timer never costs you a watch.
Each one shows up under **Watches** in the rail's **Recap**, with what it's watching, how often it checks, when it last looked, and the latest thing it found. The card's controls let you **pause**, **resume**, or **stop** a watch without saying anything.
Watches belong to the call. They stop when it ends, and they don't carry over to the next one. For something that should keep running after everyone hangs up, ask for a [job](/docs/jobs) instead. A watch also isn't the same as a [wait](/docs/channels/threads#when-an-agent-waits-for-something) in a thread: a watch keeps checking and keeps reporting, while a wait fires once and hands the conversation back.
Chat and recap [#chat-and-recap]
The right rail carries the written half of the call.
The conversation as a feed — everything spoken plus anything typed, with your agent's activity folded inline. There's a composer at the bottom, so someone who can't talk can still take part.
The call's shape as it builds — the topics you've covered, the decisions you've reached, and the questions still open — plus any **Watches** you've set. It updates while you talk.
The threads this call dispatched, with a live count on the tab. It appears once there's work to show.
When the conversation has already taken the middle of the stage — because you've muted both channels and are typing — the rail gives its column to the recap instead of repeating the transcript beside it.
On a narrow screen the rail steps out of the way and the header's **Call** / **Recap** tabs swap between the two.
Reload the page mid-call and the room fills itself back in — the conversation so far, whatever was on the stage, and your watches all come back rather than starting from blank.
Live captions [#live-captions]
Speech turns into captions as people talk, attributed by name. Captions correct themselves in place — a line may re-attribute to the right speaker once there's enough audio to be sure, so don't be surprised to see one shift as it settles.
After the call [#after-the-call]
Hang up and the room doesn't disappear — it settles. You get the same layout at rest: the tiles go static, and the recap takes the floor where the people were.
The recap reads like a good meeting note — what you covered, what you decided, and the work that came out of it — about half a page for a short call and a page for a long one. Nebula resolves every speaker to their real name first, so it reads like minutes rather than a machine dump.
The rail carries the call's numbers — **duration**, **messages**, **threads**, and **people** — over two tabs.
The recap in detail, the threads the call kicked off, and who was there.
Every turn, attributed by speaker. **Download** saves it as a plain text file you can keep or paste elsewhere.
Nebula also saves the transcript and recap as files on the call's thread, so they're reachable from the channel's **Sessions** section later. And **Start again** opens a fresh call seeded from the same thread, so a recurring conversation doesn't need setting up twice.
The recap takes a moment to appear after you hang up — it shows up once Nebula finishes writing it.
Related [#related]
# Live
You can talk to Nebula out loud. Start a call from anywhere in your workspace, bring teammates in, and the work you discuss gets picked up and run while the conversation keeps going.
A call is a thread like any other — it shows up in your sidebar, keeps its history, and leaves behind a transcript and a summary when it ends.
Starting a call [#starting-a-call]
Every entry point opens the same **Start call** dialog.
On [Home](/docs/home), the Nebula mark above the message box is the call button — it reads **Talk to Nebula**, or whatever you've named your orchestrator. Starting from here creates a fresh thread for the call, so you don't have to pick one first.
Open any thread and use the call button in the composer to talk through what's already in it. The call attaches to that thread, so its history is the context.
Start a call from a channel to pull in the people already working there. Workspace-visible calls show up for the channel's members.
**Live** in the sidebar lists everything live and everything past. **New session** starts one.
You'll see two words for this. **Live** is the destination — the sidebar entry, and this section of the docs. A **session** is one instance of it: the page lists **Sessions**, the button reads **New session**, and a channel's sidebar keeps a **Sessions** section. Inside the room itself the controls still say **call**, which is the same thing again.
**Name it** — optional. "What's this call about?" becomes the call's title in your sidebar and history. Skip it and the recap names it later.
**Pick visibility** — **Workspace** lets anyone in the workspace join; **Private** is invite-only. Workspace is the default.
**Invite people** — teammates who are online float to the top with a live dot, and **Add all** grabs everyone who's around right now. It only shows while someone online is still unpicked, so it disappears once you've got them all. Everyone you've picked appears as a chip you can click to drop again, and the button reads **Start with 2**.
Calls run right in Nebula — in your browser or the [desktop app](/docs/desktop). You drop into the room the moment you start, and the header reads **Nebula is joining** until your agent connects, so you always know where things stand. On desktop, the [Capsule](/docs/desktop/capsule) can start a call and keep its controls on screen even with the main window closed.
Who's on the call [#whos-on-the-call]
Every call runs **one agent** — your orchestrator. It's the voice you talk to, and it decides what to hand off.
The clever part is that it wears each person's identity. When Priya talks to it, it answers as *her* default agent; when you talk to it, it answers as yours. Each person's agent name works as a [wake word](/docs/live/voices#wake-words) — say it out loud in a group call and the agent speaks up without anyone reaching for a button, and you can add your own wake words too. On a call by yourself, there's no one to pair with — your agent simply stands on its own.
Specialists — , , and the rest — **don't join the call**. They pick up dispatched work in threads and report back, which is why the work board fills up while you're still talking.
You can also ask your agent to keep an eye on something for the length of the call — a thread, a search, your jobs, even your shared screen — and it checks on a loop and interrupts only when there's news. See [watches](/docs/live/in-a-call#keeping-an-eye-on-something).
How talkative your agent is during the call is up to you — see [active and background agents](/docs/live/in-a-call#active-and-background-agents).
Where calls live [#where-calls-live]
One list of every call — live ones pinned to the top, the rest ordered by recent activity. Filter to just yours or everyone's.
A channel's detail sidebar keeps its own **Sessions** section, newest first. Tap a row to expand the summary.
A blue dot pulses on the **Live** row whenever a call is running in the workspace. While you're on one, it also hangs under that row as its own entry — the call's title beside a running timer — and steps out of your **Threads** lane so it isn't listed twice. Opening it takes you into the call, not a chat thread.
When a call ends it doesn't disappear — the ended view keeps the recap and the archive, and **Start again** opens a fresh call seeded from the same thread.
You can also run a call entirely from a terminal — see [calls from the CLI](/docs/cli/calls).
Calls draw down **Nebula Credits** while they're live, billed once per call rather than per person on it. Tool Credits don't cover calls, so a call stops when Nebula Credits run out even if Tool Credits are full. See [nebula.gg](https://nebula.gg) for current plan details.
Showing your agent something [#showing-your-agent-something]
A call isn't only talking. You can put something in front of your agent and ask about it directly.
Show what's on your computer and ask what it says — a dashboard, an error, a stack trace you'd rather not read aloud.
Turn on your webcam and hold something up. Good for labels, hardware, and whiteboards.
Related [#related]
# Sharing your screen
Share your screen on a call and your agent can look at it and tell you what's there. It's the difference between describing a problem and just showing it.
Start sharing [#start-sharing]
Tap the monitor icon in the controls bar to start sharing and tap it again to stop; it tints red while you're live. The caret next to it picks quality.
| Quality | Resolution | Best for |
| ------- | -------------------- | -------------------------------------- |
| 480p | 854 × 480 @ 30 fps | The lightest option — slow connections |
| 720p | 1280 × 720 @ 30 fps | Balanced, and the default |
| 1080p | 1920 × 1080 @ 30 fps | Sharpest — dense text and code |
Your share takes the stage and the people compact into a strip alongside it. Your own screen renders back to you as a live mirror, so you can see exactly what everyone else is seeing. If a thread or a camera is already up there, they share the stage rather than replacing each other — whatever has the floor fills it, and the rest wait as thumbnails.
When you need to read dense text, the shared screen has a full-screen control in its bottom-right corner — **Open full screen**, and **Exit full screen** to come back. **Esc** also brings you back. The presenter's name and, on your own share, **Stop sharing** stay visible over the top, so you're never full-screen without a way out.
Frame rate is a ceiling, not a promise — a busy screen or a thin connection will run below it.
Letting your agent see the screen [#letting-your-agent-see-the-screen]
Your agent doesn't watch continuously. It takes a look **when you ask**, which keeps it from narrating over you while you're mid-sentence.
Ask it to describe what it sees, or to pull the text off the screen so you don't have to read a stack trace out loud.
Looking happens **in the moment** — the agent answers in the same turn rather than dispatching a thread you have to wait on. The look still shows up as activity in the chat, so you're never guessing whether it actually looked.
What it's good for [#what-its-good-for]
Share the failing screen and ask what's wrong. Because the agent re-reads whenever you ask, you can change something and ask again without restarting anything.
Stack traces, log output, error dialogs, config files — ask it to pull the text off rather than reading it aloud.
Scroll and talk. Ask about the part you're looking at, and the agent reads the current state of the screen rather than a snapshot from earlier.
Want to show your agent something *without* being on a call? On desktop, [Quick Send](/docs/desktop/quick-send) attaches a single screenshot to a message. Sharing on a call is the live version — the agent can look again as things change.
Permissions [#permissions]
The first time you share on macOS, your system asks whether Nebula can record the screen. It's the standard prompt, and you can change it later in **System Settings → Privacy & Security → Screen Recording**.
Related [#related]
Turn on your webcam and let your agent see what you're holding.
The stage, the rail, and the work board.
Attach a screenshot without starting a call.
Starting a call and who's on it.
# Voices
You pick how Nebula sounds. Browse the voice library, design a voice from a description, or clone one from a short recording — then set your default so every call starts with it.
Choosing a voice [#choosing-a-voice]
Two settings pages under your account cover this, and it's worth knowing which is which. **Voice** holds the voice Nebula speaks with on calls, alongside your mic and speaker. **Voice Library** is where you browse the wider catalog and build voices of your own.
Pick your call voice from **Settings → Voice**. Everyone starts on the same default until they change it, and your choice is **yours** — each person in a workspace picks their own, so the voice you hear isn't the voice your teammates hear.
Changing voice mid-call usually takes effect straight away, but some voices come from a different provider and can't be swapped in without restarting the connection. When that happens Nebula tells you, and the new voice starts on your next call.
Designing a voice [#designing-a-voice]
Describe the voice you want and Nebula builds it — the accent, the pace, the character of it. Preview the result, and save it to your library if it's right.
**Design voice** and **Clone voice** come from different speech providers, so only one of them is available at a time — whichever your current voice uses. If the button you want is greyed out, switch to a voice from the other provider first.
Cloning a voice [#cloning-a-voice]
Upload a recording and Nebula builds a voice from it. Keep the sample clean — one speaker, no music, no crosstalk — and you'll get a much closer match.
| | |
| -------------- | ------------------------------ |
| **Formats** | mp3, mp4, wav, ogg, webm, flac |
| **Size limit** | 25 MB per upload |
Only clone a voice you have the right to use — your own, or one you have explicit permission for.
Wake words [#wake-words]
On a call your agent listens the whole time, but how it responds depends on its [posture](/docs/live/in-a-call#active-and-background-agents). Wake words matter most in a **group call**, where an active agent deliberately stays out of the room's back-and-forth: saying one is how you tell it that this turn is for it, and it speaks up. On a one-on-one call your agent already answers every turn, so you rarely need one.
Your agent's own name is always recognized as a wake word — you can't turn that off. Beyond that, you control the triggers in **Settings → Voice**.
Saying **"Nebula"** wakes your agent by default. Turn off **Respond to "Nebula"** if the name comes up too often in conversation — the agent's own name still works.
Add your own — a nickname, a project name, whatever you actually say. Up to **five**, each **2–40 characters**, matched as whole words and case-insensitive.
Your wake words are yours, per workspace, and apply to the calls you start there. Mid-call, the in-call settings let you flip **Respond to "Nebula"** for that session only — it doesn't touch your saved defaults. Adding or editing custom words happens in **Settings → Voice**.
Mic, speaker, and noise cancellation [#mic-speaker-and-noise-cancellation]
Your audio devices have their own settings page, separate from the voice library.
Pick which mic to use, or leave it on **System default**. Until you've given your browser mic permission the list can come up empty or unnamed — join a call once and allow the microphone, and your real devices fill in from then on.
Pick where call audio plays. Same list your browser exposes.
Filters out background noise — keyboards, rooms, traffic. It's **on by default**, and it applies from the next call you start. You can also flip it mid-call from the call's settings.
These settings are per browser, not per account — set them again on a new machine. Noise cancellation depends on browser support, so the control won't appear where it isn't available.
Related [#related]
# Create a miniapp
Miniapps are small, interactive tools your agent builds inside a channel. You create one by describing it in plain language — no setup, no spec, no separate project.
How to create one [#how-to-create-one]
Ask for what you want in the channel you're already in. One sentence is usually enough. Nebula builds the app, drops an icon at the top of the channel, and messages you when it's ready to use.
Examples [#examples]
The trick isn't writing a spec. It's saying what you want to see and what you want to do with it.
A dashboard that pulls the numbers together for a specific conversation.
> Build me a board-meeting dashboard with revenue by region, a funnel breakdown, and a slider to toggle growth assumptions live.
An interactive map shaped around your actual itinerary, not a generic travel app.
> Plan our Japan trip — show the itinerary on an interactive map with our Airbnbs, day trips, and train routes.
A model you can feel, not just a spreadsheet. Sliders, live numbers, break-even lines.
> Make a pricing model where I can drag sliders for price, volume, and margin and watch break-even update.
A click-through visualization for a class, a team walkthrough, or a talk.
> Turn this into a lesson — an interactive solar system where students click planets to see orbits and compare sizes.
Related [#related]
# Miniapps
A miniapp is a small interactive tool your agent builds for you inside a channel — a dashboard, a form, a map, a picker — and you get one by describing it in plain language.
What a miniapp is [#what-a-miniapp-is]
Most of what an agent gives you is a reply. Sometimes what you actually want is a *thing*: a form your team can fill in, a chart you can filter, a map you can pan. That's a miniapp. It lives in the channel where it was made, keeps working after the conversation moves on, and anyone in the workspace can open it.
You don't specify it up front or scaffold a project. You say what you want, the agent builds it, and you refine it by asking for changes in the same thread.
Describe the tool you want in a channel and let your agent build it.
Open one beside the chat or fullscreen, and keep iterating on it.
Where they live [#where-they-live]
Every miniapp belongs to the channel it was created in, which is what keeps it findable later — the conversation that produced it is right there. The **Miniapps** row in the sidebar collects them all in one place when you'd rather go straight to the tool than back to the thread.
Because a miniapp is built by an agent, it inherits that agent's reach: the [tools](/docs/tools) it can call and the [model](/docs/models) it was created on. A miniapp spawned from a thread keeps the model that thread was on, so it doesn't quietly change behaviour underneath you.
When to reach for one [#when-to-reach-for-one]
A dashboard over data the agent has already gathered, so you can watch it change rather than re-asking for a summary each time.
A form or picker your teammates can use without needing to prompt an agent themselves — useful when the people who need the tool aren't the ones who built it.
A map, a simulator, or anything with parameters worth changing. Interactive beats a static answer when the question is "what if".
Not sure whether what you want is a miniapp or just an answer? Ask Nebula in chat — describe the outcome you're after and it will build one if that's the better fit. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# Use a miniapp
Once a miniapp exists, it's ready whenever you are. Open it inside the channel where you made it, or jump to it from the **Miniapps** row in the sidebar — the chat is always one click away.
Finding one in a channel [#finding-one-in-a-channel]
Every miniapp in a channel shows up as a small icon at the top of the conversation. Click one to open the app next to the chat.
Opening a miniapp adds a tab right next to **Chat**. Flip between the app and the conversation as you use it — the chat stays live on its own tab.
When Nebula first builds a miniapp, it drops a message into the channel pointing to it. Click through from that message and the app opens.
Using one alongside the chat [#using-one-alongside-the-chat]
Open the app from the header icon or the message where Nebula introduced it.
Use it side-by-side with the chat. The conversation keeps going on the
**Chat**
tab — ask follow-up questions, tweak the app, or move on to something else.
Close the app tab when you're done. The app stays in the channel for next time — closing the tab just tucks it away.
Iterating without leaving [#iterating-without-leaving]
Because the chat is still open on the other tab, you can keep shaping the app without switching context. Notice something you want to change? Just say so.
The Miniapps tab [#the-miniapps-tab]
The **Miniapps** row in the sidebar is the shortcut to every miniapp you've built, across every channel. It's where you go when you remember you made something and you just want it open.
Click any card to open the app in fullscreen. Great for dashboards, maps, or anything that wants more room than a side-by-side view.
Open a card's menu and pick **Pin miniapp** to keep it at the front of the list. **Unpin miniapp** puts it back in the usual order.
**Edit** opens the app with its conversation alongside, which is where you ask Nebula for changes — describe what you want different and it rebuilds.
**Manage access** decides who else can see or edit it. See [sharing and access](/docs/getting-started/sharing-and-access).
**Delete** takes it away for good when it's served its purpose. Nebula confirms first, and the app disappears from its channel too. It only shows for people who can manage the app.
Related [#related]
# Nebula on your phone
The Nebula mobile app puts your whole workspace on your phone — channels, agents, jobs, miniapps and calls — plus two things only a phone can do: share into Nebula from any other app, and get [push notifications](/docs/mobile/push-notifications).
Installing [#installing]
Nebula is on the [App Store](https://apps.apple.com/us/app/nebula-ai/id6757687588). If you were testing an earlier build through TestFlight, switch to the App Store version — the TestFlight build tells you to, and it stops there.
The Android app is in open testing on Google Play rather than a general release, so ask your workspace owner or [support@nebula.gg](mailto:support@nebula.gg) for the current link.
The app updates itself between store releases. Most of the time you won't notice; occasionally you'll open it and see **Checking for updates…**, and if one is waiting you get **Update app to login** before you can sign in. Take it — it's usually a few seconds. There's also an **Apply latest update** button in Settings if you want to pull one early.
Signing in [#signing-in]
Signing in on your phone is not the same as on the desktop app. There's no pairing code here.
Open the app. It greets you with **Welcome to Nebula** and asks for your email address.
Enter your email and choose **Continue**, or skip straight past it with **Continue with Google** or **Continue with Apple**.
If you used your email, Nebula sends you a code — the screen changes to **Check your email**. Type the code in and it signs you in as soon as it's complete. Wrong address? **Go back** returns you to the email step.
The [desktop app](/docs/desktop) signs in a different way — it shows a pairing code and confirms it in your browser. If you're looking for a code to type on your phone, there isn't one; the phone signs in on its own.
Sharing into Nebula from another app [#sharing-into-nebula-from-another-app]
This is the thing your phone can do that nothing else can. Anywhere you'd normally hit the share button — a photo, a page you're reading, a file, a screenshot — Nebula is one of the destinations.
Share as you normally would from any app, and pick **Nebula**.
Nebula opens on **Share to Channel**. Pick where it should land, or search if the list is long.
The channel opens with what you shared already in the message box. Add a sentence about what you want done with it, and send.
You can share images, video, files, text and links this way. It's the fastest route from "I'm looking at something" to "an agent is working on it."
Links work in the other direction too: a link to a Nebula thread or file opens in the app rather than the browser.
What's different in a call [#whats-different-in-a-call]
Calls work the same as everywhere else — see [Live](/docs/live) for what a call is and how to run one. Three things behave differently on a phone.
Tap the audio control to pick where sound goes: **Speaker**, **Phone**, **Headphones**, or **Bluetooth** if something's paired. The same sheet has **Noise Cancellation**, which cuts background noise around you. Echo cancellation is always on and isn't a choice.
A call keeps running when you leave the app or lock the phone, and it shows up as a real call on your lock screen, so your headset buttons and car stereo behave the way you'd expect.
You can switch between your **front** and **back** camera, or turn it off. You can watch someone else's shared screen, but you can't share your own from a phone — start that from the desktop or web app instead.
What you can't do from a phone [#what-you-cant-do-from-a-phone]
Most of Nebula is here — creating agents and miniapps, jobs, members, tools, knowledge, and your workspace settings. A few things deliberately live elsewhere.
Your phone can still create and manage [cloud devices](/docs/devices/virtual-device) and browse the files on them — it just can't be one itself.
Buying credits on your phone goes through the App Store or Google Play rather than Nebula's billing page, which is why the amounts and the receipt look different from the web. **Restore Purchases** in Settings recovers anything you've already bought. See [Workspace settings](/docs/settings/workspace#billing--credits-shared).
Related [#related]
# Push notifications
Push notifications on your phone are the one delivery destination you turn on from inside the app — open **Settings → Notifications** and choose **Enable** next to Mobile.
Turning them on [#turning-them-on]
Nebula doesn't ask for permission the moment you sign in, so if you've never been prompted, nothing is broken — you just haven't switched it on yet.
In the mobile app, open **Settings → Notifications**.
Under **Destinations**, find the row reading **Push notifications on this device.** and choose **Enable**.
Your phone asks whether Nebula may send notifications. Allow it, and the row switches on.
If you declined your phone's permission prompt earlier, **Enable** can't undo that on its own — Nebula will tell you to turn notifications on for it in your phone's own settings. Do that, then come back and try again.
Each phone is separate [#each-phone-is-separate]
A push destination is a *device*, not an account. Sign in on a second phone or a tablet and you'll enable it there too; turning it off on one leaves the others alone.
Open **Push Notifications** from your workspace's apps list to see which of your devices are registered and when each last received something. The device you're holding has an option to unregister it, which stops notifications on that phone and leaves everything else untouched.
Choosing what they tell you [#choosing-what-they-tell-you]
The kinds of things Nebula notifies you about — a task finishing, a goal completing, something needing your approval, a mention — are workspace-wide settings, not phone settings. They're the same rules that decide what reaches you by email or Slack, so setting them once covers every destination.
That's covered in [Notifications](/docs/notifications#what-you-get-notified-about), and it's the right place to go for what each event type means. Two things are worth knowing on a phone specifically:
Whatever you do with push, the in-app inbox still gets everything. Turning push off makes your phone quiet; it doesn't make you miss anything.
The mobile app only offers destinations that make sense from a phone, so desktop and browser push aren't in the list even though they exist. Manage those from the [web app](/docs/notifications).
Opening what a notification is about [#opening-what-a-notification-is-about]
Tapping a notification takes you to the thing it's about — the thread, the job, the approval — and switches you into the right workspace first if it belongs to a different one. You don't have to find your way back manually.
Nebula also keeps the unread count on the app icon in step with your inbox.
Not getting anything? Check three things in order: push is enabled for this device under **Settings → Notifications**, notifications are allowed for Nebula in your phone's settings, and the event you're expecting is actually switched on in your [notification rules](/docs/notifications). If it's still quiet, ask Nebula in chat or email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# Bring your own model
You can point Nebula at a model of your own: a vendor model it already knows about, or any OpenAI-compatible endpoint you control — including one running on your own hardware.
What you can add [#what-you-can-add]
**Add a model** in **Settings → Workspace brain → Models** opens two routes, and they solve different problems.
Pick a vendor model Nebula already knows about and make it selectable in this workspace. This is how a workspace grows its [catalog](/docs/models#the-workspace-catalog) — you're choosing from a list, not supplying an address.
Point Nebula at a URL you control. You supply the address, the model id to send upstream, and any credentials it needs. Use this for a self-hosted model, a provider Nebula doesn't list, or a gateway your team already runs.
Adding a custom endpoint [#adding-a-custom-endpoint]
Open **Settings → Workspace brain → Models** and choose **Add a model**, then the **Custom endpoint** tab.
Give it a **Display name** — this is what you'll see in the model picker and in the composer chip, so make it something you'll recognise.
Enter the **Base URL** of your OpenAI-compatible endpoint, and the **Model id** to send to it. The id is what your endpoint expects, not what Nebula shows you.
Add **Auth headers** if the endpoint needs them. These are your credentials for your own endpoint, and they're stored for that model rather than shared around the workspace.
Choose whether to restrict it to a [device](/docs/devices), then who can use it. Save, and it appears in the picker alongside everything else.
Who can see it [#who-can-see-it]
Every model you add is either private to you or shared with the workspace.
A private model carries an **Only me** badge in the table, so it's obvious at a glance which rows the rest of your team can't see.
Pinning a model to one machine [#pinning-a-model-to-one-machine]
You can restrict a custom model to a single device. When you do, only that machine runs it — a turn from anywhere else fails outright rather than quietly falling back to something else. That's deliberate: silently answering on a different model than the one you pinned is worse than an error.
This is what makes a model on your own computer work. Point the endpoint at an address on your machine — a local Ollama server, say — and lock it to your [local device](/docs/devices/local-device). Nebula routes the call through the helper already running there, so an endpoint that isn't reachable from the internet still answers.
A model reached this way replies all at once rather than word by word. The answer is the same; it just arrives complete instead of streaming in. Everything else about the conversation behaves normally.
A model locked to a **local device** is always private — that machine is yours, so the model can't be shared with people who can't reach it. Neither a private model nor a device-locked one can be the [workspace default](/docs/models#where-your-choice-lands), since the default has to work for everyone.
From the command line [#from-the-command-line]
The [CLI](/docs/cli) manages the same models, which is handy when the endpoint you're adding is on the machine you're already typing on.
| Command | What it does |
| --------------------------------- | -------------------------------------------- |
| `models custom list` | List custom models visible in this workspace |
| `models custom add` | Add one — see the flags below |
| `models custom remove ` | Delete a custom model you own |
`models custom add` takes `--alias ` for a routing alias to a catalog model, or
`--base-url ` with `--model-id ` to point at your own endpoint. Add
`--auth ` for an authorization header, `--device ` to lock it to one
machine, and `--share` to make it visible to the whole workspace. See the
[CLI reference](/docs/cli/reference#models).
FAQ [#faq]
Adding a model to the shared catalog and setting the workspace default need owner or admin. Ask an owner or admin if the option is greyed out for you — and see [Members & roles](/docs/settings/members) for who has what.
A second name for a model that's already in the catalog, useful when you want a stable name in your own tooling that you can repoint later without changing anything that refers to it. It carries a **Routing alias** badge to tell it apart from a **Custom endpoint**.
Private models and device-locked models can't be the default, because the default has to run for every member. Share it with the workspace and drop the device restriction and it becomes eligible.
An address like `localhost` means something different on every machine, so Nebula can't guess which one you meant. Naming the device removes the ambiguity — and it's what lets the request reach a machine the internet can't.
Auth headers you enter belong to that model row and are used to call your own endpoint. Ask Nebula in chat if you want to check what a model is configured with, or email [support@nebula.gg](mailto:support@nebula.gg) with anything that looks wrong.
Related [#related]
# Models and defaults
You can choose which model Nebula runs on: a tier you switch from the composer, a specific model pinned to one conversation, a workspace default that covers everything else, or a model you bring yourself.
Nebula tiers [#nebula-tiers]
Nebula's own model comes in three tiers, and you switch between them from the composer — the control sits right next to where you type and shows the tier you're on. All three are available to everyone, in every workspace, with nothing to enable first.
Answers immediately. Flash is the starting tier and the right pick for everyday back-and-forth — quick questions, short edits, anything where you're waiting on the reply.
Thinks it through. Reach for Max on involved work that needs a plan before an answer: multi-step coding, or research that has to hold a lot of context at once.
Goes deepest on hard problems. Ultra spends the most time per reply, so it's worth saving for work that's genuinely stuck or unusually intricate.
The picker only appears when you're on a Nebula model. The same menu has an **All models** entry if you'd rather pin a specific model from another provider — do that and the tier picker steps out of the way, replaced by a chip naming the model you pinned. Dismiss the chip to go back to the tier you were on.
The workspace catalog [#the-workspace-catalog]
Everything beyond the three Nebula tiers is decided per workspace, in **Settings → Workspace brain → Models**. The page has two cards: **Language models** for chat and reasoning, **Media models** for image, video, audio, speech, and transcription.
A new workspace starts with the catalog empty, so only the Nebula tiers are selectable until somebody adds to it. That's deliberate — the vendor list is enormous, and a workspace picks the handful it actually wants rather than inheriting all of it.
Members aren't locked out of the page — they see the same table with the controls greyed and a line explaining that a workspace admin manages the catalog and the default. Anything already in the catalog is theirs to use.
Need a model the workspace doesn't offer? Ask an owner or admin to add it — or ask Nebula in chat and it can walk you through what's already available. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg).
Bringing your own [#bringing-your-own]
The catalog isn't limited to models Nebula ships. **Add a model** takes either a vendor model Nebula already knows about, or any OpenAI-compatible endpoint you control — including one running on your own machine, reached through the helper on your [local device](/docs/devices/local-device).
That's a topic of its own, with the form fields, the sharing rules, and the device-pinning behaviour: see [Bring your own model](/docs/models/custom).
Where your choice lands [#where-your-choice-lands]
A model you pick **inside a conversation stays in that conversation**. It doesn't follow you to your other threads, and it doesn't repoint your jobs, your miniapps, or your agents' background work.
Pick a model while you're in a thread and it pins there. Every later turn in that thread runs on it until you change it again. Only the person who started the thread can pin it — if you pick a model in someone else's thread, it applies to your turn and doesn't stick for everyone else.
Pick a model before you've started anything and it rides along into the next thread you open, then clears. The thread after that is back on the default.
Set in **Settings → Workspace brain → Models** by an owner or admin, and marked with a star in the table. It's what any conversation uses when nobody has pinned anything. Because it's shared, changing it moves every unpinned thread in the workspace, not just yours.
A thread that never had a model pinned falls back to whatever its agent is configured for, and then to the workspace default — so leaving all of this alone is a perfectly good way to use it.
Anything Nebula spawns from a thread — a job, a miniapp — keeps the model that thread was on when it was created, so scheduled work doesn't quietly change models underneath you.
[Quick Send](/docs/desktop/quick-send) on the desktop app has its own tier picker, remembered on that device rather than shared with the workspace.
Plans: several angles at once [#plans-several-angles-at-once]
Depth isn't the only thing that changes with the tier. On **Max** and **Ultra**, when a request breaks into pieces that don't depend on each other — three things to research, a few angles to check, several options to compare — Nebula works them at the same time rather than one after another, then writes one answer from what comes back. It calls that a **Plan**.
You can watch it happen. A row of small dots appears under your message, one per step, each turning from grey to orange to green as it lands, with a running count like **3/4** beside them. Click the row to open the [activity log](/docs/channels/threads#following-an-agents-work), where every step is listed with what it found and how long it took — and any step that was waiting on an earlier one says so. Four steps run at a time, so a long plan works through in waves.
Nebula decides when a request is worth splitting up; there's no setting and nothing to turn on. Asking in plain language — *"look at these three separately, then pull it together"* — is a reasonable nudge, but it stays Nebula's call.
Flash doesn't split work up. It takes the same request in a single pass, so the answer arrives a little later on work that would have divided well.
[`/review`](/docs/slash-commands) is the one way to ask for a Plan on demand: it audits the conversation so far with several reviewers working at once, and runs on Ultra whatever tier you're on.
This isn't [plan mode](/docs/slash-commands#plan-mode), which shares the word and nothing else. A **Plan** here is Nebula splitting one request across several workers at once, decided by Nebula, and only on Max and Ultra. **Plan mode** is `/plan`: you put a thread into read-only so Nebula proposes before it touches anything, on any tier.
The default vs a per-task choice [#the-default-vs-a-per-task-choice]
The workspace default is a starting point, not a hard rule. Agents can still pick a different model for a specific task when that gets a better result.
Choosing a model [#choosing-a-model]
If you're not sure, leave it alone — the Nebula tiers handle most work well, and the composer control is there for the moments they don't. Switch to a more capable tier when you're doing heavier reasoning, and a faster one when you want quick replies.
Yes. Use the tier control in the composer, or **All models** for a specific one. The switch takes effect on your next turn and holds for the rest of that thread — your other conversations stay where they are.
Pinning a model to a thread is the thread starter's call, so the choice doesn't stick when someone else makes it. You can still start your own thread and pin whatever you like there.
The default is a workspace setting rather than a personal one, so a workspace behaves the same way for everyone in it. Pin a model to a thread when you want something different for your own work — that's yours and doesn't touch anyone else.
A model only you can see, or one locked to a single device, can't be the workspace default — it wouldn't run for everyone else. Share it with the workspace and remove the device restriction, and it becomes eligible.
Performance vs. depth [#performance-vs-depth]
Heavier models reason more deeply on complex work; lighter models reply faster and are great for quick back-and-forth. You don't have to optimize this yourself — start with the default and adjust only if replies feel too slow or not thorough enough. Because an agent can pick a stronger model for a hard step on its own, most people leave the default in place and let Nebula handle the rest.
Related [#related]
# Advanced settings
You can export a copy of your data or permanently delete your account from advanced settings. These actions are personal to your account and separate from anything that scopes to a workspace.
Export your data [#export-your-data]
Request a copy of your data when you want a backup or need it for your records.
Open your account settings and select
**Advanced**
.
Choose the export option and confirm. Nebula prepares your data.
You'll be notified when the export is ready to download.
Delete your account [#delete-your-account]
Deleting your account permanently removes your personal data. This can't be undone.
Account deletion is permanent. If you own a workspace with other members, transfer ownership first so your teammates keep access.
Open
**Settings → Advanced**
.
Select
**Delete account**
and confirm. You may be asked to re-enter credentials.
Your personal data is removed. Shared workspace content created by others is unaffected.
Account vs workspace data [#account-vs-workspace-data]
Not sure whether to delete or leave a workspace instead? Ask Nebula in chat, or email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
What an export includes [#what-an-export-includes]
An export gathers the data tied to your account — your profile, the messages you've sent, and files you've added — into a downloadable archive. Shared workspace content created by other people isn't part of your personal export. Exports are prepared on demand, so a large account may take a little longer; you'll be notified when the file is ready to download.
If you only want to step away from a single team rather than remove your account entirely, leave that workspace instead — your account, your other workspaces, and your personal data all stay intact.
Related [#related]
# Appearance and themes
You can restyle Nebula with any of its built-in themes, or generate a custom one by describing the look you want. Your choice is personal to your account and follows you to every workspace and device you sign in on.
Choose a theme [#choose-a-theme]
Open **Settings → Account → Appearance**. The **Theme** section shows the theme you're on now — its name, its family, and whether it's a dark or light palette.
Select
**Change**
to open the
**Choose a theme**
picker.
Filter by
**All**
,
**Dark**
, or
**Light**
, then browse the previews — each card renders the actual palette.
Select one. It applies instantly, everywhere you're signed in — no reload.
Nebula ships dozens of built-in themes across both dark and light palettes, and the picker tells you how many are available right now. There's no separate light/dark/system switch: **a theme is already either dark or light**, so picking one is how you choose.
In a hurry? Open the command palette with **⌘K** and run **Switch to light mode** or **Switch to dark mode**. That swaps you to Nebula's default theme for that side rather than toggling a mode.
Make your own theme [#make-your-own-theme]
The **Custom theme** section lets you generate a palette from a description or set the colors by hand. Select **Create custom theme** to open it.
Describe the look you want — the placeholder suggests ideas like *deep ocean at midnight*, *warm autumn forest*, or *neon cyberpunk*. Give it a name if you like, then select **Generate**. Nebula builds a full palette from your description and checks it for contrast before applying it.
Set ten colors yourself — background, foreground, card, primary, primary text, accent, border, success, warning, and destructive — then select **Save theme**. Use this when you have exact brand colors in mind rather than a vibe.
You get **one custom theme at a time**. Generating or saving another replaces it, and **Clear** removes it and puts you back on Nebula Dark.
**Create custom theme** always starts from the colors of the theme you're currently on, not from your saved custom theme. Treat each pass as making a new one rather than refining the last.
What a theme does and doesn't change [#what-a-theme-does-and-doesnt-change]
A theme changes **color only**. Nebula's shape and typography — corner radius, border weight, and fonts — belong to the design system, so no theme alters them. Every built-in theme is held to contrast rules, so text stays readable whichever one you pick.
It's a display preference: changing it never affects your agents, your data, your jobs, or what your teammates see.
Personal, not shared [#personal-not-shared]
Your theme is stored on your account, not on the workspace — even though you reach it from a workspace's settings.
Teammates each pick their own — switching yours never changes anyone else's, and switching workspaces keeps your choice intact.
FAQ [#faq]
Yes. Your theme is saved to your account, so the one you pick on your laptop shows up on every device where you sign in.
There's no separate mode setting. Each theme is itself dark or light, so you choose by picking a theme — use the **Dark** and **Light** filters in the picker to narrow it down.
Yes. Themes are personal to each account, so everyone on your team picks their own. It has no effect on agents or shared work.
Yes — the desktop app uses the same theme you picked, and its title bar takes its colors from it too.
No. The `nebula-ai` command-line app carries its own separate set of terminal themes. See [the CLI guide](/docs/cli) for that.
Want to change something you don't see here? Ask Nebula directly in chat. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# Approvals & the safety gate
The safety gate pauses an agent before it runs an action that looks risky — an irreversible delete, a message to someone outside your team, or anything that doesn't match what you asked — and asks you to approve it first. It's off by default, so agents act without interruption until you switch it on.
Turning the safety gate on [#turning-the-safety-gate-on]
The gate is a single on/off switch — there's nothing to configure beyond turning it on. You can flip it from three places, and they all drive the same switch.
**From the prompt bar** — click the **shield icon** to the right of the message input. Its tooltip reads **Safety gate: on** (*pauses risky actions*) or **Safety gate: off** (*runs everything*).
**From settings** — open **Account → Profile** and find the **Write approval** section. Toggle **Safety gate** on.
**From [Quick Send](/docs/desktop/quick-send)** on the desktop app — the same shield sits in that composer, so you can set it without opening the main window.
Off by default. When on, the gate applies to your actions in the current workspace — each person sets their own.
The safety gate isn't the same as [plan mode](/docs/slash-commands#plan-mode), even though both make an agent safer to run. The gate leaves an agent fully able to act and **asks you first** when something looks risky. Plan mode **takes the ability away** for the duration — the shell can't write, reach the network, or use your credentials at all, so there's nothing to approve.
What the gate catches [#what-the-gate-catches]
When it's on, Nebula reviews each write or delete an agent is about to run and pauses the ones that look **dangerous or unexpected**: irreversible deletes, sending to people outside your team, or anything that doesn't match what you asked for. Everything else runs without a prompt.
Approving an action [#approving-an-action]
When the gate fires, the agent stops and shows an approval card. The card names the action, explains **why** it was flagged, and lays out exactly what the action will do, so you can decide with full context.
If several actions are waiting, the card steps through them one at a time — *"This agent wants to run a write/delete action (1 of N pending)."*
A waiting card holds the thread [#a-waiting-card-holds-the-thread]
A card waits until it's dealt with — there's no countdown, and nothing expires out from under you while you go and check something. In exchange, an open card **holds its thread**: new messages don't send until the card is answered or dismissed, so the conversation can't run ahead of a decision nobody has made.
Only the person whose request paused the agent can answer. Everyone else sees **Waiting on *name* to respond** in place of the buttons, which keeps two people from answering the same card different ways. The composer says the same thing, so it's clear why typing isn't going anywhere.
Don't want to answer it? **Dismiss** it with the **X** in the card's header. The agent is told the input isn't coming, and it moves on with whatever it can still do rather than asking again. A dismissed write approval counts as a denial. Dismissing also clears any sibling cards still waiting in the same batch — answers you already gave stand and still run — so the thread unblocks in one go.
Want the whole run to stop rather than just this action? Send [`/stop`](/docs/slash-commands). It cancels the turn and closes the card with it, so there's no half-stopped run left to resume later.
Not every card holds the thread:
The safety gate card above — approve, deny, or always-allow a write or delete. **Holds the thread.**
The agent needs you to pick between options before it continues. **Holds the thread.**
An agent needs you to connect an app, or hand it a key it doesn't have yet. These **don't** pause anything — the agent carries on with what it can do, and the card waits. Close it with its **X** and it stays gone.
A card left alone doesn't strand the thread forever — after a couple of days the thread starts accepting messages again, and the card is still there to answer.
Approving from Slack, Telegram, or Linear [#approving-from-slack-telegram-or-linear]
If you started the work from a connected chat app, you can answer the approval there instead of coming back to Nebula. The agent posts the card into the same thread with **Approve** and **Deny** buttons, and your click resumes the run.
The card posts in-thread, headed **Action requires approval**, naming the tool and the reason it was flagged. Tap **Approve** or **Deny** and the card is replaced in place with **Approved by** *you* or **Denied by** *you*, so the thread records the decision and the buttons can't be pressed twice.
The buttons arrive as an inline keyboard under the message.
The approval arrives as a native Linear prompt on the issue.
Discord has no in-channel approval yet. An agent working from Discord doesn't pause for the gate — answer in the Nebula app instead.
Two limits worth knowing before you rely on it:
When an agent needs you to *pick between options* rather than approve an action, that card only appears in Nebula. There's no way to answer a choice from Slack, Telegram, or Linear, so those runs wait for you in the app.
The card is posted into a shared channel, but it's tied to your run. A teammate tapping **Approve** on it does nothing — same rule as in Nebula, so two people can't answer one card different ways.
The same approval always shows up in Nebula too. If the buttons don't respond — a Slack app installed before in-channel approvals shipped won't have them wired up — open the thread in Nebula and answer it there, then ask a workspace admin to reinstall the Slack app.
Always-allowed tools [#always-allowed-tools]
Choosing **Always allow** adds that tool to your own skip list for that workspace — it's yours, not the team's — so future actions from it run without a prompt for you. Review and revoke the list anytime under **Always allowed (skip the safety check)** in the Write approval section — removing a tool puts it back under the gate.
Prefer the gate's reason over blanket trust. Approve case by case while you're learning what an agent does, then reach for **Always allow** only for the tools you've seen behave.
Related [#related]
# Connected accounts
Your connected accounts are the apps *you* personally link — Gmail, Calendar, GitHub — so your agents can read your inbox, check your calendar, or post on your behalf. You add them from **Settings → Accounts**, then choose which of them each agent may use.
Connections are owned by you. When you share an agent, it still runs with **your** connections. See [Agent scoping & access](/docs/getting-started/sharing-and-access).
Your accounts vs workspace bots [#your-accounts-vs-workspace-bots]
Two different things sit under **Settings → Accounts**, in the same list: your own account connections, and the platform bots that serve the whole team.
Connections live in the workspace where you add them — they don't follow you to your other workspaces. Work in more than one? Connect the account again in each. Need shared access for the whole team? That's a [workspace bot](/docs/tools).
Connecting and disconnecting [#connecting-and-disconnecting]
Pick an app from **Settings → Accounts**.
Sign in to that service through OAuth. Nebula only asks for the permissions it needs.
The connection is now yours to hand out. Open an agent's **Tools** tab and pick this account under **Accounts** — connecting alone doesn't attach it to anything.
Disconnect any time from the same page. Past data already pulled in stays where it landed; nothing new is fetched after disconnect.
Nothing is auto-attached, so connecting an app you already use won't change how your existing agents behave. Each agent uses only the accounts you picked for it — see [choosing an account for an agent](/docs/getting-started/sharing-and-access#pick-which-account-an-agent-uses).
FAQ [#faq]
Connect them under **Settings → Accounts**. They stay private to you — a teammate's agents can't read your email or post from your account by mistake.
These belong to the whole team, so someone connects them as a [bot](/docs/tools) under **Settings → Accounts** — it doesn't have to be an admin. Every member's agents can then reach the same shared system, and whoever connected it is the one who can disconnect it.
Connect the account in each workspace where you need it — connections don't carry across. The OAuth flow picks up whichever account you're signed into at the time.
The shared Slack bot is the exception: your Slack team's install can serve several Nebula workspaces, and you can use it from any Nebula workspace you belong to. See [using Slack from more than one workspace](/docs/tools#using-slack-from-more-than-one-workspace).
Connecting and choosing are two steps. The app is on your account, but that agent doesn't have an account picked for it yet. Use the card in the chat — **Or use a connection you've already set up:** — or set it in the agent's **Tools** tab under **Accounts**.
Reconnecting repairs an account that was disconnected. It doesn't re-point an agent that's still pointed at an account which exists but no longer works — pick the account again for that agent and it'll take the new one.
Disconnect from **Settings → Accounts** and Nebula stops fetching new data right away; existing data stays where it landed. To cut access at the source too, remove Nebula in the service's own account settings.
Stuck choosing? Ask Nebula in chat — it can tell you which accounts are already connected and what your agents can reach.
Related [#related]
# Settings overview
Settings is where you configure Nebula. Everything splits two ways: **Account** settings that affect only you, and **Workspace** settings shared with everyone in your workspace. Both follow you to every device and to the web.
Using the desktop app? A handful of settings belong to that **computer** rather than to your account — its name in Nebula, Computer Control, the Capsule, and your global hotkeys. Those live in [Desktop settings](/docs/desktop/settings). Everything on this page stays here.
Account vs Workspace [#account-vs-workspace]
Pick the area that matches what you're changing — personal preferences, or shared settings for the whole team.
Your name, avatar, and username, plus the desktop and command-line apps signed in to your account. Personal to you across every workspace.
Theme and look — a personal preference that follows your account.
Pause agents before risky writes and deletes, then approve them case by case.
The apps you've personally connected in this workspace, private to you.
Shared settings: name, memories, skills, tools, usage, and billing.
Invite teammates and manage who can do what in the workspace.
Looking for **Models**? Which models your workspace can use, and which one it falls back to, lives under [Models](/docs/models) rather than in Settings — it sits alongside [Tools](/docs/tools) and [Devices](/docs/devices) as one of the things your agents work with.
What lives in a workspace [#what-lives-in-a-workspace]
A workspace is your shared world in Nebula — agents, channels, miniapps, and a Computer that you and your teammates use together. Switching workspaces switches all of it.
AI workers your team shares. Anyone in the workspace can chat with them.
Topic-based rooms with auto-summarized threads for individual conversations.
Custom interfaces — forms, dashboards, pickers — your agents can build for the team.
A shared cloud machine agents use to run code, hold files, and browse the web.
Switching workspaces [#switching-workspaces]
Open the workspace dropdown at the top of the sidebar. Picking another workspace reloads everything else — agents, channels, miniapps, devices, and even billing all scope to the workspace you're in.
Click your workspace name at the top of the sidebar.
Choose another workspace, or pick **Create Workspace** to start a new one.
The whole app re-loads scoped to the new workspace. Your URL changes too — Nebula remembers the workspace you were last in.
When to create a new workspace [#when-to-create-a-new-workspace]
Family, project team, club, classroom — anyone you want sharing the same agents and channels.
Different agents, different connected apps, different data. A workspace is the cleanest boundary.
Each workspace bills on its own. Useful for agencies, freelancers, and reimbursable work.
Need help with settings? Ask Nebula directly in chat — it can rename the workspace, invite members, and walk you through topping up Nebula Credits or Tool Credits. For anything unresolved, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# Members & roles
Add teammates to your workspace and they immediately share its agents, channels, miniapps, and Computer. You control what each member can change.
Roles at a glance [#roles-at-a-glance]
Every workspace has exactly one owner — usually whoever created it. Admins can do almost everything the owner can; members can build and collaborate but not change the org.
Workspace roles are separate from per-item access. A **member** can still keep an individual agent, job, or miniapp restricted to just themselves, or share it with named viewers and editors — see [Sharing & access](/docs/getting-started/sharing-and-access).
Inviting people [#inviting-people]
Open **Settings → Members** from the gear icon next to your workspace name. The Members table lives here.
Use the bulk-invite modal to enter one or more email addresses, pick a role for each, and send.
Each invitee gets an email with a link. You can also copy the link directly and share it however you like.
Invite links are time-limited and tied to the email address you typed. If someone misses the window, just resend.
You can also ask Nebula to invite someone from any conversation — *"invite [priya@example.com](mailto:priya@example.com) as a member"* — without opening settings at all.
Member profiles [#member-profiles]
Click anyone in the **Members** card on Home to open their profile. Any member can view it — it's a quick way to see what a teammate has built and how active they are.
Name, username, role, and a green dot if they're online right now.
Tabs for the **threads**, **agents**, **jobs**, and **miniapps** that belong to them.
A usage panel — requests and token usage over a range you choose — so you can see how heavily they're working.
What invited members see [#what-invited-members-see]
When an invited teammate accepts, they're dropped straight into your workspace — no checkout, no setup. Your billing covers them.
If they were already a Nebula user, accepting the invite just adds your workspace to their switcher. They keep their personal workspace and any other team workspaces they're in.
Removing or changing a member [#removing-or-changing-a-member]
In **Members**, click the role badge next to their name and pick a different one. Changes apply instantly.
Use **Remove** in the row menu. Their access stops right away. Anything they created — agents, channels, threads — stays in the workspace.
Open **Workspace Settings**, scroll to the bottom, and choose **Leave workspace**. The owner can't leave without first transferring ownership.
Working in more than one workspace [#working-in-more-than-one-workspace]
You can belong to as many workspaces as you like. Switch between them from the workspace name at the top of the sidebar. Each one keeps its own agents, channels, integrations, and billing.
Related [#related]
# Your profile
Your profile is yours — it follows you across every workspace you join. Workspaces have their own settings (members, billing, connected apps); your profile, theme, and timezone live at the user level and don't change when you switch between workspaces.
Open it from your account row at the bottom of the sidebar, then choose **Profile**.
Profile vs workspace settings [#profile-vs-workspace-settings]
It's worth knowing what's controlled where, especially in team workspaces:
What you can set [#what-you-can-set]
The lowercase handle teammates see in mentions and message lists. 3–30 characters; lowercase letters, numbers, and hyphens. Change it any time — old mentions update automatically.
Upload an image (PNG or JPG, square crop recommended) or let Nebula generate a colored letter avatar from your initials. Shown next to your messages everywhere.
Affects how Nebula displays times to *you* — and when your personal scheduled work fires. Workspace-level automations use the workspace timezone instead, so the team sees consistent run times regardless of who set them up.
Your theme — pick from dozens of built-in dark and light palettes, or generate a custom one from a description. See [Appearance and themes](/docs/settings/appearance).
Apps signed in to your account [#apps-signed-in-to-your-account]
**Linked apps** lists every Nebula desktop app and command-line install that can sign in as you. Each row names the machine it's running on and its version, and tells you when it was last used, so you can spot one you don't recognise.
**Revoke** signs that app out immediately — it has to pair again before it can reach your account. Use it when you hand a laptop back, lose a machine, or just stop using one.
This list is yours rather than your workspace's: it follows your account everywhere, and other members never see it. Until you sign in to the [desktop app](/docs/desktop) or the [CLI](/docs/cli) it reads **No linked apps yet** — a browser session isn't a linked app, so signing in on the web won't put anything here.
Signing out & deleting [#signing-out--deleting]
Signs you out of the current device only. Other devices stay signed in — **Linked apps** above is where you sign out a desktop or command-line install you no longer have. You remain a member of every workspace; signing back in returns you to the workspace you were last in.
Permanently removes your account, your personal workspace, and any team workspaces you own. Workspaces where you're a member but not the owner are unaffected — you're simply removed from them. The action is irreversible; export any data you want to keep first.
If you own a team workspace and want to leave Nebula without deleting it, transfer ownership to another member first from the workspace settings. Then you can leave the workspace as a regular member, and deletion only touches your personal data.
Related [#related]
# Workspace settings
Workspace settings is where you control everything that lives inside this workspace — its name and logo, what early features it turns on, who's in it, what it can connect to, and how it pays.
Open it from your account row at the bottom of the sidebar, then choose **Workspace settings**.
The Workspace tab [#the-workspace-tab]
The **Workspace** tab holds the workspace's identity and the actions that affect the whole space.
Rename the workspace and upload a custom logo. Admins and owners can edit; the change shows everywhere the workspace appears.
One switch that unlocks in-progress features for everyone in the workspace. Admin or owner only.
Step out of a workspace you're a member of. You lose access to its threads and data but stay yourself everywhere else.
Only the workspace owner can permanently delete the workspace and everything in it. This can't be undone.
Experimental features [#experimental-features]
Turn on **Experimental features** to unlock in-progress capabilities for the whole workspace before they're generally available. Only an admin or owner can flip the switch, and it applies to every member at once.
Experimental features may change or break without notice — that's the trade for early access. Turn the switch back off to hide them again.
Members [#members]
The people in your workspace are managed on their own **Members** page — invite teammates, set each person's role, and change or remove members.
See [Members & roles](/docs/settings/members) for the full role matrix and the invite flow.
The owner can't leave without first transferring ownership to another member.
Billing & credits (shared) [#billing--credits-shared]
Each workspace pays for itself. Switching workspaces switches billing context too.
Credits pay for the things agents do that cost real money, and the workspace draws on them no matter who triggered the work. They come in two kinds — **Nebula Credits** and **Tool Credits** — and the two never substitute for each other, so it's worth knowing which one a given action spends.
The distinction matters most when something stops working. Nebula Credits keep the lights on, so a full stock of Tool Credits won't keep chat, built-in tools, or device work going once Nebula Credits are gone — though anything that runs on a third-party model can still go. The reverse is gentler — with Tool Credits empty, your agents keep chatting, running jobs, and using devices, and only the third-party work is blocked.
Either way, a task that's already underway isn't discarded. Your agent carries on with the tools that still work, stops retrying the ones it can't, and finishes what it can before telling you what's blocked — so running dry mid-task costs you the blocked steps, not the whole run.
Calls draw on Nebula Credits, billed by the minute and only the minutes someone actually spoke in — a call left open in silence doesn't draw anything down. A call with six people on it costs the same per minute as a call with one.
The workspace owner and its admins. Everyone else sees the Billing tab read-only — the plan and both credit totals are visible to every member, but the top-up and plan controls aren't. If you can't top up and the workspace is running dry, that's who to ask.
A threshold and an amount that top the workspace up on their own whenever credits dip below the line. Each credit type has its own independent setting, so you can automate Nebula Credits and leave Tool Credits manual, or the other way round. Useful for workspaces that run heavy automations overnight.
Nebula Credits and Tool Credits you've topped up don't expire — they stay in the workspace until they're used. Credits included with your plan refresh on the plan's own cycle, and topping up never reduces what your plan grants you.
The workspace subscription covers every member. Invited teammates skip checkout entirely.
For current plan and pricing details, see [nebula.gg](https://nebula.gg).
Usage breakdown [#usage-breakdown]
Open **Usage** to see what's been spent. The chart groups by **Model**, **Member**, or **Agent** — useful when something looks expensive and you want to know what's driving it.
Skills [#skills]
The **Skills** area holds reusable workflows and tool definitions any agent in the workspace can call. Once a skill is added, every agent in the workspace can use it — and it stays scoped to this workspace.
See [Skills](/docs/agents/skills) for how agents discover and run them.
Need help with billing, members, or workspace settings? Ask Nebula directly in chat — it can change names, invite members, and tell you which credits are running low. Topping up is the owner's or an admin's to do. For unresolved issues, email [support@nebula.gg](mailto:support@nebula.gg). See [Support](/docs/support) for more options.
Related [#related]
# Tools and integrations
Each workspace can connect to 4,000+ services so its agents can act in the real world — post in Slack, read GitHub issues, send email, fetch from Stripe. Connections are scoped to the workspace they're added to.
You don't need to set things up in advance. When you ask Nebula to do something that needs an app, it prompts you to connect right in the conversation.
Connections belong to the person who sets them up — in workspace integrations you only see **your own**. Learn how this plays out with shared agents in [Agent scoping & access](/docs/getting-started/sharing-and-access).
Click **Connect**, sign in to the service in the popup, and grant permissions. Nebula finishes the action immediately. Future requests to the same app skip the authorization step.
If your browser blocks the sign-in window you'll get a message saying so, with a **Try again** button — clicking that reopens it properly. Backing out of the sign-in window on purpose is fine; Nebula treats it as a cancel and says nothing.
Two flavors of connection [#two-flavors-of-connection]
Connecting an app never creates a new agent. There's no "Slack Agent" or "GitHub Agent" — your existing agents simply gain the tools, and you decide which agents get them from the agent's **Tools** tab.
Connections are per-workspace. The same person can have one Slack workspace connected to their personal workspace and a different one to a team workspace. The exception is the shared Slack bot itself — a Slack team's install can serve several Nebula workspaces, and everyone on it can [use it from any Nebula workspace they belong to](#using-slack-from-more-than-one-workspace).
Popular platforms [#popular-platforms]
Connect Slack and your agents can send messages, read channels, upload and fetch files, schedule posts, and search the Slack workspace — all through the shared bot, so nobody has to sign in individually.
The Slack bot token is at the Slack workspace level. Anyone in the channel can interact with it. Make sure the Nebula bot has been added to the Slack channels you want it to read.
Connect Discord and your agents can post in channels, create and join threads, and read a server's pinned messages.
Discord is deliberately read-and-post only. Moderation and administration — kicking, banning, pinning, managing roles, channels or webhooks — are held back on purpose, as is listing server members, so an agent can't take a destructive action in a server you share with other people.
The Discord bot is connected per-server. One server per workspace today; switch workspaces to talk to a different server.
Connect Telegram and your agents can DM you, post in groups, send photos and documents, run polls, and create invite links for groups the bot has been added to. It can read a group's details, members and admins, but it can't kick or ban anyone.
Twitter (X) is not a workspace bot — you connect **your own** X account by OAuth, and it stays yours. Pick it for an agent in that agent's **Tools** tab and it can post and reply on your behalf.
To post on a schedule, ask Nebula for a [job](/docs/jobs) — the scheduling is Nebula's, not X's.
Supported integrations [#supported-integrations]
Beyond the four messaging platforms, Nebula connects to Gmail, GitHub, Notion, Linear, Stripe, Shopify, Google Calendar, Salesforce, HubSpot — and so on. Search the full catalog. If your app supports OAuth, chances are it works.
How OAuth connections work [#how-oauth-connections-work]
When you connect an external service, Nebula securely manages the OAuth token exchange, credential storage, and API communication. Credentials are encrypted; Nebula only accesses what you authorize. Revoke any connection at any time from **Settings → Accounts**.
If a service doesn't support OAuth, you can connect it with an **API key** or token. Generate the key in the service with the minimum scopes you need, then paste it into the variable form in the agent's details panel — never into a chat message.
Multiple accounts [#multiple-accounts]
If you have multiple accounts for the same service (two Slack workspaces, two Gmails), Nebula asks which one to use before taking action. You can connect as many as you need.
Custom MCP servers [#custom-mcp-servers]
Beyond the built-in catalog, you can connect any remote **MCP server** by URL and hand its tools to your agents. There's no form to fill in — you register one by asking Nebula in chat, and it lands in **Settings → Accounts** like any other row.
Give it the URL and Nebula works the rest out, asking only where it genuinely can't guess:
A **name**, the server's **URL**, and a **slug** — the server's tools then appear under an `mcp:` toolkit named for that slug. It picks a sensible slug from the name unless you ask for a particular one.
One of four: **none**, an **API key**, a **custom header**, or **OAuth**. Pick OAuth and there's nothing to paste at all — you sign in instead. For the others, store the secret as a variable and refer to it by name so the raw value is never sitting in a chat message.
`https://` URLs only — a hosted server, not a local `npx` or stdio command. Transport is Streamable HTTP or SSE.
Signing in to an OAuth server [#signing-in-to-an-oauth-server]
A server set to OAuth gets a **Connect** button and a status of its own in the list. Every app in the catalog reports its health the same way — **Connected**, **Needs setup**, **Needs attention**, or **Not connected** — so an MCP server reads exactly like a Slack bot does. Click **Connect** and a sign-in window opens; approve there and you're done.
Nebula keeps the connection alive on its own, so **Needs attention** only appears when it genuinely can't renew and needs you to sign in again. Two different removals sit on the detail view: **Disconnect my account** drops your own sign-in and leaves the server in place, while **Remove** followed by the server's name takes it out of the workspace for everyone — it warns you first that agents using it will lose those tools.
The server registration is **workspace-scoped**, but an OAuth connection is **yours**. Each member signs in with their own account, so a teammate using the same server acts as themselves rather than as you.
If an agent needs a server nobody has connected yet, it can drop a **Connect** card straight into the conversation — sign in from there and it picks the work back up. Anyone else in the thread just sees that it's waiting on you.
Registered servers are **workspace-scoped**. To let an agent use one, attach its `mcp:` toolkit from the agent's **Tools** tab with **Connect a tool**, the same way you'd add any other tool.
Coding harnesses [#coding-harnesses]
Connect a **coding harness** — **Claude Code** or **OpenAI Codex** — so your agents can delegate whole-repository coding work to it. Harnesses sit at the top of **Settings → Accounts** under **Coding Accounts**, and each person connects their own: a harness connection is private to you, not shared across the workspace.
The **This machine** option runs the CLI already signed in on a [device](/docs/devices) — available only when the agent runs on that machine, and Nebula stores no credential.
Each harness has a **Model** picker that keeps itself current: when a new model or tier turns up on your plan, it appears in the list on its own. Codex reads the lineup from your own ChatGPT plan, so two people in the same workspace can genuinely see different options. Usage sits beside the picker as **Session (5h)** and **Weekly** bars.
Working with Claude Code sessions on your device [#working-with-claude-code-sessions-on-your-device]
With Claude Code connected, your agents can also see and steer the Claude sessions running on your own machine — the ones you started yourself at the terminal, not just work Nebula dispatched. Ask in plain language and Nebula reaches the `claude` CLI on the device directly.
Ask what's running and you get the sessions on your devices with what each is working on. Nebula answers from what it last recorded rather than interrupting the machine, and it tells you how old that reading is — so *"nothing is running"* and *"I haven't managed to look"* never get confused for each other. Ask it to check again for a fresh read.
Send a follow-up instruction into a session that's already going, and it continues that same session rather than opening another. You can also interrupt the current answer without ending anything — Claude drops the turn and stays ready for your next instruction.
Start a fresh session for genuinely separate work, or **fork** one to try a different direction from the conversation so far. A fork leaves the original untouched and running, so both continue side by side.
End a session for good. Stopped sessions can't take further instructions — reach for an interrupt instead if you only want to change course.
Everything here runs on your machine at your pace: Nebula hands off the instruction and Claude keeps working, so progress arrives in the thread rather than making you wait on a reply.
Three things have to be true before a session will start, and Nebula says which one stopped it:
A machine another workspace member can reach won't run a session, because the Claude signed in on it can't be shown to be yours. This is the same setting as [device sharing](/docs/devices/local-device#sharing-your-computer-with-teammates) — add someone to your computer and Claude Code sessions there stop working, observing included. If you want both, keep a machine to yourself for this.
Sessions run on your Claude plan. An **API key** connection is turned down for this specifically — a session relays its output into Nebula's storage as it goes, and a prompt that printed your environment would write your key there with it. One-shot coding work doesn't carry that risk and still accepts a key.
Nebula refreshes your plan sign-in before starting and declines if what it gets back won't outlast the session. Better to be told now than to have Claude stop mid-conversation.
Managing your connections [#managing-your-connections]
Two pages under **Workspace brain** split the job between them, and it's worth knowing which is which: **Tools** is what your agents can *do*, **Accounts** is what they're *signed in to*.
What you've already connected, in one list: your app accounts like Gmail and Notion, the platforms that run as a workspace bot — Slack, Discord, GitHub, Linear, Telegram — your [MCP servers](#custom-mcp-servers), your custom toolkits, and your [coding harnesses](#coding-harnesses). At rest the page lists what you've connected and nothing else, so it stays short. Start typing in its search box and it widens to the whole catalog, so you can find something you haven't connected yet without leaving the page — or use **Add Account** to browse the catalog outright. This is where connecting, reconnecting and disconnecting happen.
The built-in tools your agents can use straight away, with no account to connect — search, code execution, image generation and the rest. Each has a per-member availability setting — **Off**, **On demand** (used only when an agent explicitly needs it), or **Always on** — and that choice is *yours*: it controls what your agents reach and doesn't change anyone else's setup. You can also turn the whole store off.
**On demand** isn't a one-way door: an agent turns the capability back on itself the moment it needs it. **Off** is the deliberate stop — an agent can't reach past it, and it'll tell you the capability is unavailable rather than pretending it tried.
Some tools aren't yours to change: where a tool ships on by default, the setting is greyed out and the panel tells you **Every agent has this by default** instead of offering a choice that wouldn't stick.
Kinds aren't split across separate tabs — a Slack bot and a Gmail account are rows in the same **Accounts** list, each badged for what it is.
Reading an app's status [#reading-an-apps-status]
Every row carries a coloured dot and a word, and they mean the same thing whatever kind of app it is.
| Status | What it means |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| **Connected** | Working. Nothing to do. |
| **Needs setup** | The workspace side is done but something is still missing — usually your own account isn't linked yet. |
| **Needs attention** | A credential exists but has stopped working. Reconnect to fix it. |
| **Not connected** | Nothing set up yet. |
Click any row to open its detail view: what it can do (its **Actions**, **Webhooks**, and **Endpoints**), which agents are using it, and every action available to you. Actions you can't take stay visible with the reason attached rather than disappearing.
Who owns a connection [#who-owns-a-connection]
Connecting an app is a personal act, not a workspace one. Whoever clicks **Connect** owns that connection, and that ownership — not an admin role — decides who can take it away.
Try to remove a connection you didn't make and Nebula says so plainly: *"Only the person who connected this can disconnect it. Connecting is personal now, so a workspace admin cannot remove someone else's connection."* If the person who connected it has left and the connection has broken, connecting again replaces it with your own.
Admin standing still governs **routing** — where a bot's incoming work lands. That lives on its own page, because reading an installation's channel map reveals which workspaces a team's channels point at.
Using Slack from more than one workspace [#using-slack-from-more-than-one-workspace]
A Slack team can be connected to several Nebula workspaces, and you can use it from any Nebula workspace you belong to. If the bot is connected but Nebula doesn't recognise your Slack account yet, the app's detail view offers **Link my Slack account** under **Your account** — a personal identity link, not an installation, so you don't need to be an admin.
When a connection is live somewhere else, Nebula says so on the row. It names the workspace when you're a member of it — *"Connected in Acme — connect it here to use it in this workspace"* — and stays vague when you aren't: *"Your Slack account is connected in another workspace, not this one."*
Either way the fix is the same, and it runs forwards rather than backwards: connect Slack from the workspace that wants it. There's no control for lending an existing installation to a second workspace from the workspace that already has it.
Having trouble connecting? Ask Nebula for help, or email [support@nebula.gg](mailto:support@nebula.gg).
Related [#related]
# Webhooks
A webhook is a URL that other tools can send data to. Give Nebula's webhook URL to another tool, and whenever that tool has new data, it sends it to Nebula, which can then trigger your agent to take action.
How to create a webhook [#how-to-create-a-webhook]
Ask Nebula to create a webhook [#ask-nebula-to-create-a-webhook]
Say something like: "Create a webhook I can use to trigger this agent from Zapier."
Get your unique URL [#get-your-unique-url]
Nebula gives you a webhook URL of the form `https://api.nebula.gg/webhooks/triggers/`. It's shown in the job's details under **Webhook** — copy it from there rather than typing it out.
Paste it into your other tool [#paste-it-into-your-other-tool]
Go to Zapier, Make, your custom backend, or wherever you want to send data from, and paste in the URL.
Send data and watch it work [#send-data-and-watch-it-work]
When your other tool sends a request to the webhook URL, Nebula receives it and your agent handles it.
Example use cases [#example-use-cases]
**Zapier**: trigger your Nebula agent whenever a new row is added to a Google Sheet, a form is submitted, or any of Zapier's 6,000+ triggers fire.
**Make**: build visual workflows in Make that send data to Nebula as one step in a larger automation.
**Custom backends**: send events from your own application directly to Nebula. For example, notify your agent when a new user signs up or a payment completes.
Having trouble connecting? Ask Nebula for help, or email [support@nebula.gg](mailto:support@nebula.gg)
Related [#related]