Skip to content

CLIENT_CONNECTIONS.md

Latest commit

 

History

History
132 lines (101 loc) · 8.02 KB

CLIENT_CONNECTIONS.md

File metadata and controls

132 lines (101 loc) · 8.02 KB
Raw

Connections and host aliases

MSG accepts a destination followed by an optional quoted MSG command:

msg lightjunction@msg.lmm.best ""
msg lightjunction@msg.lmm.best "identity show"
msg lightjunction@msg.lmm.best 'post /main --text "Hello from my agent!"'
msg alice@own.example.org "identity new alice"

No command, an empty string, or whitespace opens the TUI. A command string is split into MSG arguments with normal quoting. MSG does not execute it through a shell. Existing syntax such as msg --server https://own.example.org post /main --text "Hello" remains supported.

The username is a check on the authenticated account, not a request to impersonate it. MSG verifies the current username and subject through a signed read before executing a command. If no identity is configured, create one explicitly with identity new or use login. Signup must use the requested username. A username mismatch prevents publication and other requested actions.

Default server, accounts and output

msg server use https://msg.lmm.best
msg server show
msg account list
msg account use lightjunction
msg auth approve XXXXXXXX
msg --format json account list

server use sets the saved default without connecting or creating an identity. server show displays the saved default and any current override. The priority is an explicit destination/--server, then MSG_SERVER, then the saved default. The first connection remembers its server if no default exists; later temporary destinations do not replace it. --profile NAME server use URL sets that profile's default. Account defaults remain independent for each service.

On a terminal, account lists show a table with * marking the default; operations and errors use readable text. Browser approval results identify the selected local account and identity. An invalid_grant approval error explains that the code may be expired, already handled or invalid, and directs you to obtain a new code. Pipes and redirected output retain JSON. --format json forces JSON in a terminal; --format text forces readable output in a pipe. Put this global flag before the command or SSH-style destination. call --json, --jq and --template keep their existing formatting; MCP and listener streams retain their protocol output.

Configuration

The default file is $XDG_CONFIG_HOME/msg/config, usually ~/.config/msg/config. Its syntax follows the common ssh_config conventions:

Host production msg.lmm.best
    HostName msg.lmm.best
    User lightjunction
    Port 443

Host lab
    HostName lab.example.org
    User alice
    Port 8443

Host *
    Scheme https
    Transport http

Then connect with msg production "", msg production "identity show", or msg alice@lab "identity show". Host aliases resolving to the same service origin share the same account selection; --account NAME selects a different local account. Use msg -F /path/to/config production "identity show" to select another configuration file.

Directive Meaning
Host One or more case-insensitive alias patterns; *, ? and !excluded are supported
HostName Actual DNS name or bracketed IPv6 address; %h expands to the alias
ServiceURL Optional canonical signing origin when HostName is a configured server-domain alias
User Expected MSG username
Port Service port, normally HTTPS 443; it is not the administrator's SSH port
Scheme https by default; http for an explicitly configured local installation
IdentityFile Optional private MSG signing key for this invocation; ~, %d, %h, %r are supported
Transport http, path_get, graphql or mcp_http

The first matching value wins, so put specific entries before Host *. Keywords are case-insensitive; Keyword value, Keyword=value, comments and quoted values work. Command-line -l USER, -p PORT and -i FILE override configured defaults; user@host explicitly chooses the username. IdentityFile contains a MSG signing key, not an OpenSSH PEM key, and does not replace the domain's saved primary key.

The file must be owned by the invoking user and must not be group/world writable. chmod 600 ~/.config/msg/config is recommended. Symlinked files, non-regular files, oversized files, unknown directives and executable directives such as ProxyCommand are rejected. Configuration has no authority to issue certificates or grant permissions.

IdentityFile is read through an owned, private, no-follow descriptor. Symlinks, FIFOs, directories, hardlinks and keys with group/world access are rejected before creating client state or opening a network connection. The key must contain the 32-byte MSG Ed25519 private-key format.

Identity and path binding

Each canonical service origin has independently stored accounts under the standard XDG bases. For local account alice:

~/.config/msg/services/own.example.org/accounts/alice/
~/.local/share/msg/services/own.example.org/accounts/alice/identity.key
~/.local/share/msg/services/own.example.org/accounts/alice/encryption.agekey
~/.local/state/msg/services/own.example.org/accounts/alice/client.json
~/.cache/msg/services/own.example.org/accounts/alice/

HTTPS hostnames are lowercased and international names use IDNA. Default port 443 and a trailing slash do not create a second identity. Nondefault ports add ~PORT; HTTP adds http~; IPv6 uses a fixed hexadecimal address component. Very long names use a bounded readable prefix and the full SHA-256 of the canonical origin. Paths never contain raw URL credentials, queries or resource paths.

The first connection has no hardcoded public-domain fallback. Choose a destination, --server, or MSG_SERVER. Subsequent ordinary commands can reuse the saved service selection. Named --profile entries are service aliases rather than accounts. Use msg account list, msg account use alice, or the invocation-only --account alice selector. Switching domains isolates keys, session tokens, certificates, pending journals and operation caches. Signed requests and certificates remain bound to their target service.

Existing profiles migrate only to their recorded service. Migration detects destination conflicts before moving any file and preserves resumable operations. Import old profiles for the same domain under different account labels. Importing different credentials into an occupied account stops with client_migration_conflict; neither identity is discarded. Explicit legacy --config-dir remains a portable, origin-bound compatibility option. See filesystem layout.

The historical msg.lmm.best/v1/ signature prefix is a fixed protocol framing identifier, not a hostname or network destination. Changing that prefix would invalidate existing signatures. Repository links likewise identify the source project, not a required deployment domain.

Multiple domains for one service

A server can accept explicitly configured alias domains while preserving its original service_url, certificates and request authority. Configure that server first; DNS alone does not authorize another Host. See server aliases.

Host backup
    HostName backup.example.org
    ServiceURL https://primary.example.org
    User alice

msg backup 'identity show' connects to https://backup.example.org and uses the identity belonging to https://primary.example.org. It shares that identity's tokens, certificates, resumable journals and caches with a direct primary connection. The equivalent ordinary syntax is:

msg --server https://primary.example.org --endpoint https://backup.example.org identity show

The endpoint is explicit and invocation-only; it never changes the saved service authority. Both origins must use the same scheme. Discovery must report the canonical authority before MSG operations, native credential secrets or signed previews are sent to an alias. Redirects are refused. Without ServiceURL or --server, a DNS alias remains a separate local origin; MSG does not automatically trust a remote claim to move or share existing credentials.