Cloud Files and Networking

This page explains how to move files and secrets to a machine, how to open its ports and desktop, how its private network works, and how to publish a URL.

Upload and download files

cmux vm push uploads a file or folder to a machine. The transfer is checked with SHA-256. By default it skips .git, node_modules, .venv, __pycache__, and .DS_Store. Use --no-default-excludes to include them, --exclude to skip more paths, and --watch to upload changes again as you save.

cmux vm push brave-otter ./app ~/app
cmux vm push brave-otter . ~/repo --no-default-excludes
cmux vm push brave-otter . ~/repo --exclude dist --watch
cmux vm pull brave-otter ~/repo/report.html ./report.html

One upload can be up to 256 MB. For a large repository, clone it inside the machine.

cmux vm pull downloads a file from a machine.

Secret files

cmux vm push --secret uploads a small file, up to 256 KB, over the encrypted cmux link. The file is written with mode 0600 by default. Use it for keys and credentials instead of a normal upload.

cmux vm push --secret brave-otter ~/.npmrc ~/.npmrc

Environment variables

cmux vm env stores variables in ~/.config/cmux/env on the machine's disk. Every new shell loads them. Values travel over the encrypted link and are not echoed. cmux vm env ls hides values unless you add --show.

cmux vm env set brave-otter --from-file .env
op read op://dev/stripe/key | cmux vm env set brave-otter -
cmux vm env ls brave-otter
cmux vm env rm brave-otter STRIPE_KEY

KEY=VALUE arguments can stay in your local shell history. Use --from-file or standard input for secrets.

Ports and the in-app browser

Start a dev server on a machine and ⌘-click the localhost URL in the Cloud terminal. cmux opens it in a browser pane at the machine's private address. Servers that listen only on localhost also work. You do not need a VPN or port forwarding.

cmux vm ports lists the ports that are open on a machine. The Cloud sidebar shows them under Ports. cmux vm open machine:port/number opens one.

cmux vm ports brave-otter
cmux vm open brave-otter:port/3000

Desktop

Every machine has a Linux desktop. Open it from the machine menu with Open Desktop, or run cmux vm desktop. It opens in a browser pane over VNC. GUI apps, Chrome, and browser automation run on this display.

cmux vm desktop brave-otter

Private network

Your machines have no public inbound ports. cmux gives each account a private network, and each Mac connects with its own WireGuard key that never leaves the Mac. The connection starts inside the cmux app and needs no approval.

Your machines can reach each other on the same private network.

The Cloud Mac access page on cmux.com lists the Macs that can reach your machines. Rename or revoke a Mac there. Revoking a Mac signs it out and removes its access to all machines.

System VPN (optional)

cmux vpn up adds a system route so other apps on your Mac, such as a separate browser or database client, can reach your machines. cmux itself does not need it. The first time, approve the cmux network extension in System Settings › General › Login Items & Extensions. cmux vpn down turns it off.

cmux vpn up
cmux vpn status
cmux vpn down

Public URLs

cmux cloud domains publish gives a port on a machine an HTTPS URL. The generated hostname ends in .cmux.sh.

cmux cloud domains publish brave-otter 3000
cmux cloud domains publish brave-otter 3000 --access team
cmux cloud domains publish brave-otter 8080 --access public --yes
cmux cloud domains list
cmux cloud domains grant <hostname> teammate@example.com
cmux cloud domains rm <hostname>

Each URL has an access mode. The default is the machine's owner: you, or your team when a team owns the machine.

• personal: only you can open it.
• team: current members of the team that owns the machine can open it.
• public: anyone with the URL can open it. cmux asks you to confirm.

For personal and team URLs, visitors sign in on a cmux page first. The machine never sees cmux cookies. You can also give one email address access to one URL with cmux cloud domains grant.

Treat a public URL like a password. Anyone who has it can use the service.

Custom domains

cmux cloud domains verify prints the DNS records to add: a TXT record for ownership, the routing records, and the certificate delegation. Add them, then run verify again. After verification you can publish on the domain or on a subdomain one level below it.

cmux cloud domains verify preview.example.com
cmux cloud domains publish brave-otter 3000 --domain app.preview.example.com