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:brew upgrade vms.
Download the file
Download the file for your computer from the latest release, withSHA256SUMS:
Check the file. Then rename it to
vms, make it executable, and move it to a folder in your PATH:
vms ssh needs OpenSSH. vms cp -r from a sandbox needs tar. macOS and most Linux systems have both.
Sign in
With your browser
- The CLI shows a code and a link, and opens the link in your browser.
- Sign in, if you are not signed in.
- Check that the page shows the same code as your terminal. Choose Approve.
- 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, andtemplates: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:VMS_API_KEY. Each command uses it before the saved key:
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 asagent-42 or sbx_06d8k3m7q2v9x4b1n5c0e8f2ja. Run vms <command> --help to see the options of a command.
new
running. It writes the sandbox ID to stdout.
ls
ssh
ssh.vms.dev.
- It adds the host key of
ssh.vms.devto~/.ssh/known_hosts, so thatsshdoes not ask you to trust the host. After that,ssh agent-42@ssh.vms.devalso 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 withCould not connect to ssh.vms.dev. Check your network.It saysThe sandbox did not accept the SSH keyonly when the sandbox refuses the key.
exec
- 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
<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. -rcopies 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 runstarin the sandbox.- A copy into the sandbox keeps the file mode, such as
0755.
stop
stopped. Use --no-wait to return at once. See Stop and resume a sandbox.
resume
running. Use --size to change the size. Use --no-wait to return at once.
rm
url
?_token=.
See Open a port of a sandbox on a public URL.
fork
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
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
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.