Skip to main content
vms creates and uses sandboxes from your terminal. It is one file with no dependencies, for macOS on Apple silicon, macOS on Intel, and Linux on x86-64.

Install

With Homebrew

On macOS or Linux:
To get a new version, run brew upgrade vms.

Download the file

Download the file for your computer from the latest release, with SHA256SUMS: Check the file. Then rename it to vms, make it executable, and move it to a folder in your PATH:
The macOS files are not notarized. If you download the file with a browser, remove the quarantine attribute before you run it. If you do not, macOS can refuse to open it:
vms ssh needs OpenSSH. vms cp -r from a sandbox needs tar. macOS and most Linux systems have both.

Sign in

With your browser

  1. The CLI shows a code and a link, and opens the link in your browser.
  2. Sign in, if you are not signed in.
  3. Check that the page shows the same code as your terminal. Choose Approve.
The CLI then makes an API key for one workspace and saves it. If you are a member of more than one workspace, give the workspace:
  • You need the Owner or Admin role in the workspace. A member can sign in with an API key from an owner or an admin.
  • The key has the scopes workspace:read, sandboxes:read, sandboxes:write, sandboxes:exec, sandboxes:files, sandboxes:ssh, sandboxes:desktop, snapshots:read, templates:read, and templates:write. It gets only the scopes that your role permits. It expires after 90 days.
  • The key has the name vms CLI on <computer name>. You can see it and revoke it in Settings, then API keys. See API keys.
  • The code expires after 10 minutes. On a computer without a browser, open the link on a different computer.
  • The CLI saves the key in ~/.config/vms/config.json, which only your user can read. It does not save your password or your sign-in session.

With an API key

Send the key on stdin, so that it does not go into your shell history:
Or set VMS_API_KEY. Each command uses it before the saved key:
The key needs the scopes of the commands that you use. See Scopes for each command.

Sign out

vms logout revokes the key that vms login made with the browser, and removes the saved key. It does not revoke a key that you gave with --with-api-key or VMS_API_KEY.

Commands

Give a sandbox by its name or by its ID, such as agent-42 or sbx_06d8k3m7q2v9x4b1n5c0e8f2ja. Run vms <command> --help to see the options of a command.

new

Creates a sandbox and waits until it is running. It writes the sandbox ID to stdout.

ls

Lists the sandboxes of the workspace, with the ID, the name, the state, the size, and the creation time.

ssh

Opens a shell in the sandbox, or runs one command, through ssh.vms.dev.
  • It adds the host key of ssh.vms.dev to ~/.ssh/known_hosts, so that ssh does not ask you to trust the host. After that, ssh agent-42@ssh.vms.dev also connects with no question.
  • It adds your public key to the sandbox. The key is ~/.ssh/id_ed25519. If you do not have this key, the CLI makes a key in ~/.config/vms/ssh/.
  • Use -i <file> to use a different private key.
  • If your computer cannot reach ssh.vms.dev, it stops with Could not connect to ssh.vms.dev. Check your network. It says The sandbox did not accept the SSH key only when the sandbox refuses the key.
See Connect to a sandbox with SSH.

exec

Runs a command and streams its stdout and stderr. The CLI exits with the exit code of the command.
  • Put -- before the command, so that the options of the command do not go to the CLI.
  • One argument runs in a shell, so you can use && and pipes. More arguments run the program with no shell.
  • When stdin is not a terminal, the CLI sends it to the command.
See Run commands in a sandbox.

cp

Copies files between your computer and a sandbox. Write a sandbox path as <sandbox>:<absolute path>. One of the two paths must be in a sandbox.
  • A target that ends with / is a folder. The file keeps its name in it.
  • -r copies the content of a folder into the target folder. To copy into the sandbox, the CLI sends the files in one tar upload. To copy out of the sandbox, it runs tar in the sandbox.
  • A copy into the sandbox keeps the file mode, such as 0755.
See Read and write files.

stop

Stops each sandbox that you give, and waits until it is stopped. Use --no-wait to return at once. See Stop and resume a sandbox.

resume

Starts each sandbox that you give, and waits until it is running. Use --size to change the size. Use --no-wait to return at once.

rm

Deletes each sandbox that you give, with its files. You cannot undo this.

url

Gives a port of the sandbox an HTTPS URL, and writes the URL to stdout. If the port has a URL, the CLI writes that URL. A URL that is not public has its token in ?_token=. See Open a port of a sandbox on a public URL.

fork

Makes new sandboxes with the files and the environment variables of a running or stopped sandbox, and waits until each fork is running. It writes the ID of each fork to stdout, one on each line. A fork of a running sandbox gets the files of a new snapshot. See Fork a sandbox.

template

See Save a sandbox as a template.

snapshot

Give a snapshot by its ID, or give a sandbox to use its latest snapshot. The sandbox can be stopped or deleted. Use -o <file> to write to a file. The CLI does not write a tar to a terminal. Use --json with ls to write the list as JSON. See Read the files of a snapshot.

desktop

Opens the desktop of a running sandbox in your default browser. The link stops working 10 minutes after the CLI makes it, if nobody opens it. When no browser opens, the CLI writes the link to stdout. See See the desktop of a sandbox.

Scopes for each command

Environment variables

Exit codes