Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(spaces): explain computers, devices and Spaces; fix paired boolean defaults in the CLI reference (#6093)

injaneity6feba694ee07
diff --git a/docs/content/docs/agents/add-a-machine.mdx b/docs/content/docs/agents/add-a-machine.mdx
index 770068b477..85ca9ad7ba 100644
--- a/docs/content/docs/agents/add-a-machine.mdx
+++ b/docs/content/docs/agents/add-a-machine.mdx
@@ -60,3 +60,6 @@ firewall and the token, and try again. Don't open the port wider to make it pass
- The token is kept apart from the Space list, readable only by your user.
- Your user can forget it with `cua spaces rm <name>`. That does not stop the
machine: stop it with the cloud's own CLI.
+- It is a Space reached by its address (`direct:<address>:3211`), not one of
+ your user's computers or devices. How they differ:
+ [Computers, devices and Spaces](/spaces/concepts/computers-devices-and-spaces).
diff --git a/docs/content/docs/cua-cli/reference/cli/images-and-clouds.mdx b/docs/content/docs/cua-cli/reference/cli/images-and-clouds.mdx
index 23ffe121ba..c873e4d4c8 100644
--- a/docs/content/docs/cua-cli/reference/cli/images-and-clouds.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/images-and-clouds.mdx
@@ -533,7 +533,7 @@ cua cloud connect [OPTIONS] <PROVIDER>
| <span id="cua-cloud-connect--token-stdin"></span>`--token-stdin` | boolean | `false` | Hetzner or Modal: read the API token from stdin (Hetzner: a Read & Write project token, otherwise `HCLOUD_TOKEN`, the saved token or the hcloud CLI's context; Modal: `<token id>:<token secret>`). Once the checks pass it is sealed to your devices, or with --no-sealed saved in this device's Cua credential store (Hetzner). |
| <span id="cua-cloud-connect--default"></span>`--default` | boolean | `false` | Also make it the default location (`default.on`). |
| <span id="cua-cloud-connect--oidc"></span>`--oidc` | boolean | `false` | Link without a stored key: Cua's issuer signs 15-minute tokens your account trusts (AWS, Google Cloud; Azure always). |
-| <span id="cua-cloud-connect--sealed"></span>`--sealed` | boolean | `false` | Hetzner, Modal: seal the API token to your devices (the token given on stdin, else the one this device has). The default when this device has the account's pool keys and a budget is given. |
+| <span id="cua-cloud-connect--sealed"></span>`--sealed` | boolean | | Hetzner, Modal: seal the API token to your devices (the token given on stdin, else the one this device has). The default when this device has the account's pool keys and a budget is given. |
| <span id="cua-cloud-connect--no-sealed"></span>`--no-sealed` | boolean | `false` | Hetzner: keep the API token on this device only (in the Cua credential store), as before sealing. |
| <span id="cua-cloud-connect--check"></span>`--check` | boolean | `false` | With --oidc (and Azure): prove the link works (a check token, the exchange with the cloud, a dry run, permission check or validate; nothing is created) and save it. |
diff --git a/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
index 439119cd4b..eea97316de 100644
--- a/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
@@ -595,9 +595,9 @@ cua host setup [OPTIONS]
| <span id="cua-host-setup--profile"></span>`--profile` | `desktop` \| `spare` | | What this computer is for: `desktop` (share this desktop, and provide Spaces on a new relay setup; the default) or `spare` (do not share the desktop; provide Spaces). |
| <span id="cua-host-setup--max-spaces"></span>`--max-spaces` | integer | | Provided Spaces at once (default 4; 0: no limit). |
| <span id="cua-host-setup--remote"></span>`--remote` | boolean | `false` | When sign-in is needed, use a device code to approve it in a browser on another computer. The account session is not saved. |
-| <span id="cua-host-setup--desktop"></span>`--desktop` | boolean | `false` | Share this computer's own desktop as a Space. |
+| <span id="cua-host-setup--desktop"></span>`--desktop` | boolean | | Share this computer's own desktop as a Space. |
| <span id="cua-host-setup--no-desktop"></span>`--no-desktop` | boolean | `false` | Do not share this computer's own desktop (screen, input, shell, files): relayed callers reach only the Spaces it provides. |
-| <span id="cua-host-setup--provide-spaces"></span>`--provide-spaces` | boolean | `false` | Create Spaces for your enrolled devices on this computer's runtimes (Lume macOS VMs, Docker Linux containers). The default for a new relay setup; a computer set up before keeps its setting unless this (or `--no-provide-spaces`) is given. On its own it keeps the default `desktop` profile, so this computer's desktop is shared too; add `--no-desktop` (or use `--profile spare`) to provide Spaces only. |
+| <span id="cua-host-setup--provide-spaces"></span>`--provide-spaces` | boolean | | Create Spaces for your enrolled devices on this computer's runtimes (Lume macOS VMs, Docker Linux containers). The default for a new relay setup; a computer set up before keeps its setting unless this (or `--no-provide-spaces`) is given. On its own it keeps the default `desktop` profile, so this computer's desktop is shared too; add `--no-desktop` (or use `--profile spare`) to provide Spaces only. |
| <span id="cua-host-setup--no-provide-spaces"></span>`--no-provide-spaces` | boolean | `false` | Do not create Spaces for other devices (only share this desktop). |
| <span id="cua-host-setup--dedicated"></span>`--dedicated` | boolean | `false` | This computer exists only for Cua work (a cloud instance made for it; `cua cloud add aws` sets its hosts up this way): jobs may run in its own Space (`kind = "machine"`), with its GPU and drivers as they are. Never on a computer you also use: there jobs run in macOS VMs or containers. |
diff --git a/docs/content/docs/spaces/concepts/computers-devices-and-spaces.mdx b/docs/content/docs/spaces/concepts/computers-devices-and-spaces.mdx
new file mode 100644
index 0000000000..24d0dc50f2
--- /dev/null
+++ b/docs/content/docs/spaces/concepts/computers-devices-and-spaces.mdx
@@ -0,0 +1,33 @@
+---
+title: Computers, devices and Spaces
+description: 'The difference between a signed-in device, a machine, its shared desktop and a sandbox Space, and why one computer can show up twice.'
+---
+
+One computer can be both a device you connect from and a machine that runs
+Spaces. These names describe different roles:
+
+| Name | What it is | Where you see or use it |
+| --- | --- | --- |
+| Signed-in device | A computer enrolled to reach your account's machines, once, with a second factor. Signing in does not make it a host. | **Settings > Devices** or `cua devices ls`, with an id such as `dev_…`. |
+| Machine | A computer set up with **Add a computer** or `cua host setup` to share its desktop, provide Spaces, or both. | The **Computers** page. When **Provide Spaces** is on, `--on host:<machine-id>` creates new Spaces on it. |
+| The machine's shared desktop | The computer's own screen, input, shell and files as a Space, while **Share this desktop** is on. It is not a sandbox. | `relay:<machine-id>` for a computer set up on the relay. A direct host (set up with `--direct`, no relay record) is its own `direct:<host:port>` Space, added with `cua spaces add <host:port> --host`. For a relay computer, its row on **Computers** says **Desktop shared**, or **Desktop · 2 Spaces** when it also runs Spaces; the desktop is not counted among them. |
+| Sandbox Space | A container, VM or microVM created for work, on this computer or on a machine that provides Spaces. See [Space kinds](/spaces/concepts/space-kinds). | `local:<name>` on this computer. On a relay machine that provides Spaces it has its own `relay:` id, with `host` naming the computer that runs it. On a direct host (set up with `--direct`, no relay) it has a `direct:<host:port>` id, whether created on that host or added by address. |
+
+**Share this desktop** and **Provide Spaces** are separate settings. Hosting
+alone never enrolls a computer as a device: a computer that only hosts joins
+with its own token and can't reach your other computers.
+
+## Why one computer can show up twice
+
+A computer set up with `cua host setup` on the relay has a machine record. (A direct host, set up with `--direct` and no relay, has no relay record and is listed from your laptop's own host list.) Signing in on
+that computer, in the app or with `cua auth login`, also gives it a device
+record. The relay keeps the two apart and doesn't link them: they are one
+computer in two roles, not two computers.
+
+The **Computers** page joins them into one row when it can match them safely,
+for example by the same id or matching names. If the match is unclear, such as
+two Macs with the same name, they stay as separate rows. A row that is only a
+device is not a host, so **Run on** in **New Space** never offers it.
+
+See [Add a computer](/spaces/guides/add-a-computer) for the two settings and
+[How Spaces works](/spaces/concepts/how-spaces-works#space-ids) for Space ids.
diff --git a/docs/content/docs/spaces/concepts/how-spaces-works.mdx b/docs/content/docs/spaces/concepts/how-spaces-works.mdx
index b983625d38..e595a98529 100644
--- a/docs/content/docs/spaces/concepts/how-spaces-works.mdx
+++ b/docs/content/docs/spaces/concepts/how-spaces-works.mdx
@@ -13,6 +13,10 @@ you own or rent. A **Space** is one desktop on a computer, set up for a task. A
Space is a container, a VM or a microVM, or the computer's own desktop. See
[Space kinds](/spaces/concepts/space-kinds).
+A computer you also sign in on is a device too, a separate record, so one
+computer can show up twice. See
+[Computers, devices and Spaces](/spaces/concepts/computers-devices-and-spaces).
+
Cua doesn't rent computers. You bring them, and your cloud provider bills you for
any VM you run in your own account. Cua provides the app, sharing and the relay
that lets your devices reach your computers.
diff --git a/docs/content/docs/spaces/concepts/meta.json b/docs/content/docs/spaces/concepts/meta.json
index 40efa373ca..9384535dd8 100644
--- a/docs/content/docs/spaces/concepts/meta.json
+++ b/docs/content/docs/spaces/concepts/meta.json
@@ -2,6 +2,7 @@
"title": "Concepts",
"pages": [
"how-spaces-works",
+ "computers-devices-and-spaces",
"space-kinds"
]
}
diff --git a/docs/content/docs/spaces/guides/add-a-computer.mdx b/docs/content/docs/spaces/guides/add-a-computer.mdx
index b62fa857c8..625bec79cd 100644
--- a/docs/content/docs/spaces/guides/add-a-computer.mdx
+++ b/docs/content/docs/spaces/guides/add-a-computer.mdx
@@ -224,6 +224,9 @@ directly when the two networks allow it (on the same LAN that is the LAN),
through the relay as ciphertext otherwise. The relay introduces the two and
never holds the keys.
+For how this computer, its device record and its Spaces fit together, see
+[Computers, devices and Spaces](/spaces/concepts/computers-devices-and-spaces).
+
The computer has two settings, and each works on its own:
| Setting | What it does | `desktop` profile (default) | `spare` profile |
diff --git a/docs/content/docs/spaces/meta.json b/docs/content/docs/spaces/meta.json
index ef6be8ab7a..1de2f2fdc6 100644
--- a/docs/content/docs/spaces/meta.json
+++ b/docs/content/docs/spaces/meta.json
@@ -5,6 +5,7 @@
"index",
"quickstart",
"concepts/how-spaces-works",
+ "concepts/computers-devices-and-spaces",
"concepts/space-kinds",
"---Get started---",
"guides/install",
diff --git a/scripts/docs-generators/cli-mdx.test.ts b/scripts/docs-generators/cli-mdx.test.ts
index 09b58d98db..c88057670c 100644
--- a/scripts/docs-generators/cli-mdx.test.ts
+++ b/scripts/docs-generators/cli-mdx.test.ts
@@ -4,6 +4,8 @@ import {
type CLIDocumentation,
type CliReference,
displayType,
+ flagsTable,
+ type FlagDoc,
renderCliReference,
splitExamples,
} from './lib/cli-mdx';
@@ -177,6 +179,33 @@ test('examples split from help text', () => {
assert.deepEqual(splitExamples('No examples'), { prose: 'No examples', examples: [] });
});
+test('a boolean flag with a --no- sibling leaves its default to the description', () => {
+ const enabled: FlagDoc = { name: 'provide-spaces', help: 'Enable Spaces', default_value: false };
+ const disabled: FlagDoc = { name: 'no-provide-spaces', help: 'Disable Spaces', default_value: false };
+ const force: FlagDoc = { name: 'force', help: 'Overwrite', default_value: false };
+
+ const table = flagsTable([enabled, disabled, force]).join('\n');
+ assert.ok(table.includes('| `--provide-spaces` | boolean | | Enable Spaces. |'));
+ assert.ok(table.includes('| `--no-provide-spaces` | boolean | `false` | Disable Spaces. |'));
+ assert.ok(table.includes('| `--force` | boolean | `false` | Overwrite. |'));
+
+ const ordinary = '| `--provide-spaces` | boolean | `false` | Enable Spaces. |';
+ assert.ok(flagsTable([enabled]).join('\n').includes(ordinary));
+ assert.ok(flagsTable([enabled, { ...disabled, hidden: true }]).join('\n').includes(ordinary));
+ assert.ok(
+ flagsTable([enabled, { name: 'no-provide-spaces', help: 'Mode', type: 'String', is_optional: true }])
+ .join('\n')
+ .includes(ordinary)
+ );
+
+ const display = flagsTable([
+ { name: 'display', help: 'Resolution', type: 'String', is_optional: true, default_value: '1024x768' },
+ { name: 'no-display', help: 'Headless', default_value: false },
+ ]).join('\n');
+ assert.ok(display.includes('| `--display` | string | `1024x768` | Resolution. |'));
+ assert.ok(display.includes('| `--no-display` | boolean | `false` | Headless. |'));
+});
+
test('types read as types', () => {
assert.equal(displayType({ type: 'NAME' }), 'string');
assert.equal(displayType({ type: 'Int' }), 'integer');
diff --git a/scripts/docs-generators/lib/cli-mdx.ts b/scripts/docs-generators/lib/cli-mdx.ts
index 71d51d953f..6289e924d6 100644
--- a/scripts/docs-generators/lib/cli-mdx.ts
+++ b/scripts/docs-generators/lib/cli-mdx.ts
@@ -323,7 +323,8 @@ function flagDescription(opt: OptionDoc | FlagDoc): string {
/**
* `Flag | Short | Type | Default | Env var | Description`; the Short and
- * Env var columns are dropped when no row uses them. `path` (the command
+ * Env var columns are dropped when no row uses them. A boolean flag with a
+ * `--no-<name>` boolean sibling has an empty Default. `path` (the command
* path) gives every flag its own anchor; omit it for tables that are not
* under a command (global options).
*/
@@ -347,7 +348,10 @@ export function flagsTable(options: Array<OptionDoc | FlagDoc>, path?: string[])
: '';
} else {
type = 'boolean';
- def = codeCell('false');
+ // `--x` beside `--no-x`: its default depends on something else (its help
+ // says what), so `false` would be wrong. `--no-x` is off unless given.
+ const hasInverse = visible.some((o) => o.name === `no-${opt.name}` && !takesValue(o));
+ def = hasInverse ? '' : codeCell('false');
}
const row = [
flag,