Computer control from the CLI
Turn any machine into a Nebula local device with one command — choose whether agents can run commands, manage the daemon, and know where they work from.
nebula-ai local-device enable turns the machine you're on into a local device your agents can use. It's the headless counterpart to the desktop app's 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 <path> to name one explicitly and it confirms with Working folder set to <path>.
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 <path> 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 naming teammates under People with access on the device in the desktop app's Settings → Workspace → Devices (see Computer control). There's no CLI command for it, and no admin override.
Whether agents can run commands
Registering a device and letting agents execute commands on it are two separate decisions.
| host | none | |
|---|---|---|
| Agents can run commands | Yes | — |
| Files in the working folder | Yes | Yes |
| Set with | local-device exec-mode set host | local-device exec-mode set none |
| Best when | It's your own dev machine | You want file access without a shell |
host is the CLI's equivalent of the desktop app's Allow using my computer; none is Don't allow.
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
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
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. Only enabling from another
workspace 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 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 <path> says otherwise.
An ACP editor session 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 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.
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 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
Nebula CLI
Run Nebula from your terminal. Install the nebula-ai CLI, sign in once, and use the full-screen app to chat, join calls, and drive your workspace.
Command reference
Every nebula-ai command and subcommand, plus the global flags, environment variables, JSON output for scripting, shell completion, and the logs.