Sharing and Space networks

Share a port, file or folder as a link or a public TCP address, set what a Space can reach and where its traffic leaves, the exit through this computer, and the paths between your computers.

Command	Description
`cua share`	Share a link to a port, a file or a folder that opens on your other signed-in devices (never localhost): `cua share 3000`, `cua share ./report.html`, `cua share ls`, `cua share stop ID`.
`cua share ls`	List the active shares.
`cua share stop`	Stop a share (its link stops working at once), or `all`.
`cua share check`	Open a share's link once, as its owner, and say what came back.
`cua share approve`	Let a waiting public TCP share go live: one an agent in a Space asked for, or the first through a share edge in your cloud.
`cua share deny`	Turn down a waiting public TCP share.
`cua share settings`	Where public TCP shares go, the daily data cap, the default allowlist and the approval rule; with no flags, shows them.
`cua network`	What a Space can reach on the network, and changing it: `show`, `set`, `log`.
`cua network show`	What a Space can reach: its preset, what it opens, where it is enforced, and what is always blocked.
`cua network set`	Change what a Space can reach.
`cua network log`	What a Space tried to reach and was blocked, most recent first.
`cua hotspot`	Send a Space's internet traffic out through this computer for a while: `start`, `stop`, `status`.
`cua hotspot start`	Send a Space's internet traffic out through this computer's network until `cua hotspot stop` (its own rules still apply).
`cua hotspot stop`	Stop it.
`cua hotspot status`	Whether it is on, and what it carried.
`cua mesh`	How traffic reaches your other computers: `status` (and `--prefer`).
`cua mesh status`	The path to each other computer (local network, direct or relay), its round trip and why it was chosen.

Every command also accepts the global options.

`cua share`#

Share a link to a port, a file or a folder that opens on your other signed-in devices (never localhost): cua share 3000, cua share ./report.html, cua share ls, cua share stop ID.

cua share [OPTIONS] <TARGET>
       cua share <COMMAND>

Argument	Type	Default	Description
`<TARGET>`	string	required	What to share: a port (`3000`), a port in a Space (`space:NAME:3000`), or a file or folder (`./report.html`, `./build/`). Paths are read-only; use `./ls` for a file called `ls`.

Flag	Short	Type	Default	Description
`--ttl`		string		How long the share lasts (`10m`, `1h`, 60s to 24h). Public shares default to 1h; the others have no end unless you set one.
`--name`		string		A name for `cua share ls` (and `cua share stop NAME`).
`--service`		string		With --tcp: the game or service (`minecraft`), for a name people can type instead of the address.
`--route`		`auto` \| `host` \| `edge` \| `relay`		With --tcp: how people reach it. `auto` (default) takes the Space's own host in your cloud, else a small server in your linked cloud (a share edge), else Cua's relay, within `cua share settings`.
`--allow`		string		With --tcp: only these addresses or CIDRs may connect (repeat it). Default: the settings' allowlist, usually anyone. Repeatable.
`--team`		boolean	`false`	Share with the members of your team.
`--public`		boolean	`false`	Anyone with the link can open it. Expires (default 1h, 60s to 24h).
`--tcp`		boolean	`false`	Share a raw TCP service in a Space (a game server, for example) at a public address instead of a link: anyone with the address can connect, for 24h unless --ttl says less. Needs --public and a port in a Space (inside a Space, a bare port is its own). An experiment: turn on Public TCP shares in Settings, Labs.
`--check-host`		boolean	`false`	With --tcp --service minecraft: drop connections that did not dial this share's address (scanners, stale addresses).
`--yes`	`-y`	boolean	`false`	With --tcp: agree to the share edge's cost without asking (the first share through your cloud creates a small server there).

Examples

# A dev server on this machine, for your own devices (phone included)
cua share 3000
 
# A port inside a Space
cua share space:dev:3000
 
# A report or a folder, read-only
cua share ./report.html
cua share ./build/
 
# Members of your team
cua share 3000 --team
 
# Anyone with the link, for an hour
cua share ./report.html --public --ttl 1h
 
# A game server in a Space, at a public address (Labs: Public TCP shares)
cua share space:mc:25565 --tcp --public --service minecraft
 
# The same from an agent inside the Space (its own port)
cua share 25565 --tcp --public --service minecraft
 
# Through your own cloud only, for two friends' addresses
cua share space:mc:25565 --tcp --public --route edge --allow 203.0.113.7 --allow 198.51.100.0/24
 
# A share an agent asked for, waiting for you
cua share approve share-1a2b3c4d5e6f
 
# Where public TCP shares go, the daily data cap and the default allowlist
cua share settings
 
# What is shared, and stop it
cua share ls
cua share stop share-1a2b3c4d5e6f
cua share stop all

`cua share ls`#

List the active shares.

cua share ls [OPTIONS]

Examples

# What is shared right now
cua share ls
 
# The same as JSON
cua share ls --json

`cua share stop`#

Stop a share (its link stops working at once), or all.

cua share stop [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required	The share's id or name from `cua share ls`, or `all`.

Examples

# Stop one share by its id
cua share stop share-1a2b3c4d5e6f
 
# Stop everything this machine shares
cua share stop all

`cua share check`#

Open a share's link once, as its owner, and say what came back.

cua share check [OPTIONS] <ID> [PATH]

Argument	Type	Default	Description
`<ID>`	string	required	The share's id or name.
`<PATH>`	string	optional	A path below the link to open.

Examples

# Does the link load?
cua share check share-1a2b3c4d5e6f
 
# Open a page below the link
cua share check share-1a2b3c4d5e6f /index.html

`cua share approve`#

Let a waiting public TCP share go live: one an agent in a Space asked for, or the first through a share edge in your cloud.

cua share approve [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required	The waiting share's id.

Flag	Type	Default	Description
`--always`	boolean	`false`	Let its Space's agents share without asking from now on.

Examples

# See what waits, then approve it
cua share ls
cua share approve share-1a2b3c4d5e6f
 
# And let that Space share without asking from now on
cua share approve share-1a2b3c4d5e6f --always

`cua share deny`#

Turn down a waiting public TCP share.

cua share deny [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required	The waiting share's id.

Examples

cua share deny share-1a2b3c4d5e6f

`cua share settings`#

Where public TCP shares go, the daily data cap, the default allowlist and the approval rule; with no flags, shows them.

cua share settings [OPTIONS]

Flag	Type	Default	Description
`--land`	`auto` \| `only-my-cloud` \| `allow-relay`		`auto`, `only-my-cloud` or `allow-relay`.
`--relay`	`on` \| `off`		Whether Cua's relay may carry public TCP shares at all.
`--daily-cap`	string		The most data public TCP shares move in a day (`2GB`, `500MB`, `off`).
`--allow`	string		The allowlist new shares start with (repeat it). Repeatable.
`--approve-agents`	`on` \| `off`		Ask before an agent's share goes public (`on`, the default).
`--allow-anyone`	boolean	`false`	New shares are open to anyone (clears the allowlist).
`--remove-edge`	boolean	`false`	Remove the share edge from your cloud now; its shares end.

Examples

# Show them
cua share settings
 
# Never through Cua: only your own cloud
cua share settings --land only-my-cloud
 
# A 5 GB daily data cap, or none
cua share settings --daily-cap 5GB
cua share settings --daily-cap off
 
# New shares only for these addresses
cua share settings --allow 203.0.113.0/24
 
# Remove the share edge from your cloud now
cua share settings --remove-edge

`cua network`#

What a Space can reach on the network, and changing it: show, set, log. An experiment: see cua experiments.

cua network [OPTIONS] <COMMAND>

`cua network show`#

What a Space can reach: its preset, what it opens, where it is enforced, and what is always blocked.

cua network show [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Examples

cua network show studio
cua network show local:studio --json

`cua network set`#

Change what a Space can reach. A child Space stays within its parent's unless --widen.

cua network set [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Flag	Type	Default	Description
`--network`	string		`internet`, `none`, `localhost:<ports>` (or `localhost:all`), `lan`, `custom`, `custom:none` or `unprotected` (No protection). Left out: the preset it has (to change only `--via`).
`--via`	string		Where its internet traffic leaves: `internet` (its own network, the default), `this-computer` (this computer's network: the hotspot), `space:<name>` (a Space of its tree) or `socks5://host:port`. Its rules apply first; if the exit goes away, its internet stops (it never falls back). A child keeps its parent's. Left out: the exit it has.
`--allow`	string		Allow this destination (IP, CIDR, or a name such as `pypi.org` or `*.github.com` on runtimes behind the Cua network gateway; repeat for more). Repeatable.
`--deny`	string		Block this destination (IP, CIDR, `all`, or a name on runtimes behind the Cua network gateway; repeat for more). A deny wins over the Space's own tree: it blocks a member of the tree too. Repeatable.
`--widen`	boolean	`false`	A child Space: let it reach more than its parent (recorded on the Space).
`--tree`	boolean	`false`	Its child Spaces get the same settings (each within its parent's).

Examples

# This computer's Postgres and dev server only
cua network set studio --network localhost:5432,3000
 
# Your local network too
cua network set studio --network lan
 
# Only these destinations
cua network set studio --network custom:none --allow 140.82.112.0/20
 
# Back to the default
cua network set studio --network internet
 
# Its internet traffic leaves through this computer (the hotspot)
cua network set studio --via this-computer
 
# ... or through another Space of its tree, or a SOCKS5 proxy
cua network set worker --via space:gateway
cua network set studio --via socks5://proxy.example:1080
 
# Its own network again
cua network set studio --via internet

`cua network log`#

What a Space tried to reach and was blocked, most recent first.

cua network log [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Examples

cua network log studio

`cua hotspot`#

Send a Space's internet traffic out through this computer for a while: start, stop, status. (cua network set --via this-computer keeps it.) Part of the Secure Spaces experiment.

cua hotspot [OPTIONS] <COMMAND>

`cua hotspot start`#

Send a Space's internet traffic out through this computer's network until cua hotspot stop (its own rules still apply).

cua hotspot start [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Flag	Type	Default	Description
`--bypass`	string		Destinations that keep the Space's own network (repeat). Repeatable.
`--system-proxy`	boolean	`false`	Point the Space's system proxy (and new processes' ALL_PROXY) at it. Otherwise apps use the SOCKS address it prints.

Examples

cua hotspot start studio
cua hotspot start studio --system-proxy --bypass 10.0.0.0/8

`cua hotspot stop`#

Stop it.

cua hotspot stop [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Examples

cua hotspot stop studio

`cua hotspot status`#

Whether it is on, and what it carried.

cua hotspot status [OPTIONS] <SPACE>

Argument	Type	Default	Description
`<SPACE>`	string	required	Space id or name.

Examples

cua hotspot status studio --json

`cua mesh`#

How traffic reaches your other computers: status (and --prefer). Part of the Secure Spaces experiment.

cua mesh [OPTIONS] <COMMAND>

`cua mesh status`#

The path to each other computer (local network, direct or relay), its round trip and why it was chosen. --prefer pins it.

cua mesh status [OPTIONS]

Flag	Type	Default	Description
`--prefer`	string		Pin the path: `lan` (the local network whenever it answers), `direct`, `relay`, or `auto` (fastest; lifts the pin). Traffic never stops: a pinned path that goes away falls back.

Examples

cua mesh status
cua mesh status --prefer lan
cua mesh status --prefer auto

Exit codes#

Code	Meaning
`0`	Success.
`1`	Failure, or `cua do` reported an error.
`2`	Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`).
`3`	Not found: sandbox, window, skill or image (or an image not published yet).
`4`	Not supported, or not configured (for example no provider credentials).
`5`	No cua-spacesd answered, or a transport failure.
`6`	Unauthenticated or permission denied (by Cua or your cloud account).
`7`	Not enough free disk space (see `cua cache`).
`8`	No room on the machine: its VMs are at their memory or CPU limit, or it is low on memory.
`130`	Cancelled (Ctrl-C during a create): what it made was removed.

Sharing and Space networks

cua share#

cua share ls#

cua share stop#

cua share check#

cua share approve#

cua share deny#

cua share settings#

cua network#

cua network show#

cua network set#

cua network log#

cua hotspot#

cua hotspot start#

cua hotspot stop#

cua hotspot status#

cua mesh#

cua mesh status#

Exit codes#

`cua share`#

`cua share ls`#

`cua share stop`#

`cua share check`#

`cua share approve`#

`cua share deny`#

`cua share settings`#

`cua network`#

`cua network show`#

`cua network set`#

`cua network log`#

`cua hotspot`#

`cua hotspot start`#

`cua hotspot stop`#

`cua hotspot status`#

`cua mesh`#

`cua mesh status`#