First connection

This page walks you through creating a session, connecting to the server, and trusting its host key the first time.

Create a session

macSCP starts with a session sidebar on the left of the window. To create your first connection:

1. Click New Tab (⌘N) or the new-connection action in the sidebar.
2. Pick the protocol: SSH for SFTP over SSH, S3 for S3-compatible object storage, or WebDAV.
3. Fill in the connection details:
   • SSH — host, port (22 unless your server says otherwise), user name, and a password, a key file, or your SSH agent as the login. Entries from ~/.ssh/config appear automatically.
   • S3 — access key, secret key, endpoint and region. Hetzner Object Storage has one preset per location, and an S3 session can start at the account’s bucket list instead of one fixed bucket. Enter the endpoint as a server address, such as https://s3.example.com. The access key and secret key have fields of their own; an endpoint with an @ anywhere after the server name is refused.
   • WebDAV — the server URL, user name and password, the authentication method (Basic, Digest, or TLS), or the one-click Nextcloud/ownCloud preset.
4. Save the session. Its password or key passphrase lives only in the macOS Keychain — see Security.

Resolving a host name

For an SSH session, Resolve… beside the host field looks the name up and offers its addresses in a Use address menu — IPv4 first, then IPv6. Choosing one replaces the host name in the field with that address. The button is greyed out while the field is empty or already holds an address; a name that does not answer within 5 seconds reads “The name did not resolve in time.”

Caution

Connecting to an address instead of the name asks you to confirm the server’s host key again, and the name is not kept.

Organizing sessions

Saved sessions are organized in the sidebar with groups, tags, and an inline rename. Clicking a session shows its details before you connect: connection facts, recent connections, and its snippets with a one-click Run.

Connect

Double-click the session, or click Connect in its overview. The tab opens with the two-pane browser: your Mac on the left, the server on the right.

If the connection fails, the tab stays open and offers the way forward — edit the connection, or run the connection diagnostics straight from the error message. Details… shows the full reason.

A failure you need to read — a rejected key, a missing passphrase — appears in a Connection failed alert on the connection form, with Diagnose… and OK. It stays until you dismiss it, even when you select another session in the sidebar; after that, the session’s overview returns. Error messages never show a user name or password that was typed into a server address.

A server that does not start SFTP no longer leaves the tab waiting: the attempt ends when the wait for the file session times out, and Details… says “This server did not start SFTP. It may not offer SFTP at all.”

How long a connect waits

Settings → SSH → Connect Timeout bounds two stages of a connection separately: waiting for the server to answer, and waiting for it to open the file session. The number applies to each of them, and between them sits a fixed waiting period this setting does not cover — so a connection that fails takes noticeably longer than the seconds you set before the tab gives up. Through a jump host, reaching the server from the jump host is not covered either.

Confirm the host key on first connect

The first time macSCP connects to an SSH server, it shows the server’s host key fingerprint and asks you to confirm it. Check the fingerprint against what your server administrator tells you (or against the server console), then confirm. The key is then pinned to that session.

• An unknown key needs your explicit consent — nothing connects behind your back.
• A changed key is a hard stop: macSCP refuses the connection and never shows a dialog that would let you click past it. This is what a man-in-the-middle attack looks like; verify out of band, then update the pinned key in Sessions → Known Hosts (⌘⇧K).

See Security for the full host-key rules.

Transfer your first file

With both panes showing files, move one:

• Drag a file from one pane to the other (or straight into the Finder), or
• Select it and press ␣ (space) to transfer it to the other pane.

The transfer appears in the transfer queue; see Transfers for conflicts, parallel transfers, and resuming after a connection loss.