Skip to content

First run

After the installation process has resulted in a running msksd systemd user service, it's almost ready to use. But you need to supply your ssh keypair and import at least one image used as a base for workspace creation before you can succesfully create one.

Make sure it's running

Before trying to connect to msksd via the client, make sure it's running.

On Linux, to see status and log output from the account the daemon runs as (the service is a systemd user unit):

  systemctl --user status msksd
  journalctl --user -u msksd -f          # follow the daemon's log

On macOS, do the following (the daemon runs inside the Lima VM, as a systemd system unit):

  limactl shell msksd -- systemctl status msksd
  limactl shell msksd -- sudo journalctl -u msksd -f   # follow the daemon's log

When msksd is first started on Linux (or within the Lima VM that runs Linux on Mac), it creates a state dir (~/.local/state/msksd). The msksd.yaml config file is generated within it as a commented template (see Configuration).

The unix listener binds $XDG_RUNTIME_DIR/msks/msksd.sock. Same-host Linux clients connect through it on peer-credential authentication. A remote can, if configured, contact a TLS/https listener with a bearer token. That's how it works on macOS.

With the host prepared, the service lingered, and an image imported, invoking the msks (the client) on the same account will find the socket.

The key files

You need to configure an ssh key before msksd/msks will work properly.

Every workspace msks uses your public ssh key as the workspace's operator identity.

Every msks ssh and msks rsync session uses your private half.

msks also allows you to manage secrets for workspaces. The same ssh key locks workspace secrets on the daemon: values a workspace needs at runtime are sealed under the identity, and the client unlocks them with the private half again.

The client names the key in its YAML file (~/.config/msks/msks.yaml) or its environment, with two keys:

identity_file: ~/.ssh/id_ed25519 # the private half
pubkey_file: ~/.ssh/id_ed25519.pub # the public half

If your identity is typically in your ssh agent, you needn't specify the identity-file, just the pubkey_file. But it's more foolproof to specify both at first.

identity_file: the private half

identity_file names your private key file, read in place. msks derives the public half from it at create, and the key file is never copied into msks's state

But session resolution consults your own ssh-agent first. When SSH_AUTH_SOCK names a live agent holding that key, every session signs through the agent and the file's encryption stops mattering. The match is on key material, so the file it came from and its name do not matter (ssh-add it). If your key is saved in your ssh-agent, you needn't name the private half of your key in msks config, only the public one (pubkey_file), and the private half need not be on disk.

If your ssh key is not already in an agent, a key no agent holds is staged in memory as an unencrypted OpenSSH-format key (ed25519, ecdsa P-256/P-384/P-521, or rsa). msks never types a passphrase.

A passphrase-encrypted identity_file raises the session's one passphrase prompt when the daemon's locked secret rows need it. The TUI asks once when the tree opens, and the answer unlocks every locked secret row for the session. Escape or Cancel leaves the secrets locked. They stay named on the secrets page and re-askable there.

pubkey_file: the public half

pubkey_file names a .pub file, and a create with it set plants that one line as the workspace's identity and reads no private material at all. This is the form for a key you keep encrypted on disk: the public half sits in the .pub file while the private half answers from your agent.

msks console will wok to access a wokspace if you've lost your key.

Where the private half lives at runtime

An agent-held key stays in the agent: msks asks it to sign, and the file on disk is never opened. A key msks stages itself runs in a transient in-process agent that dies with the session. And a session you forward your agent into (ssh_options with -A) carries the agent you named into the workspace. The workspace identity msks mints stays separate, and your keys arrive only where you forwarded them.

With neither key naming a usable source, msks create refuses with a line saying so. It is the one command that needs the identity at its start.

Importing a guest VM image

On first run, a workspace image has not been imported, so you are not able to create guest VMs. A workspace image arrives either from the published channel (msks image import in the TUI, or the images chapter's URL form) or from a local build.

These images are hosted on github, and the TUI enumerates them for you and allows you to import one. There are currently Debian and NixOS guest images corresponding with the most recent msks release.

The first run's image page: the catalog empty, the published channel enumerated; the import modal holds the terminal while the daemon downloads