Servers dialog (write-only keychain secret, test connection, unknown and changed host key), status-bar progress with Cancel, Deployment log tool window, Upload/Download in the project tree menu and Tools › Deployment. docs/deployment.md, architecture section, G17 row. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.5 KiB
Deployment
Status: Deployment v1 (C9 D1, owner decision D27): servers per project, upload, download, upload on save, test connection, host keys, Deployment log. Remote browser, compare and sync follow in D2 · Last updated: 2026-11-06
Lutra uploads a PHP project to a server and downloads files back, the way people deploy shared hosting and small servers every day.
Servers
Open Tools › Deployment › Servers…. Each project has its own list; one is the default server (the only one is the default automatically).
| Field | Meaning |
|---|---|
| Name | Shown in the log, the status bar and toasts. |
| Type | SFTP (SSH), FTPS (FTP with explicit TLS, certificates checked against the system's trusted roots), FTP (unencrypted: everything, including the password, crosses the network in clear text; prefer SFTP or FTPS), or a local or mounted folder. |
| Host, Port, User | Port defaults to 22 (SFTP) or 21 (FTP, FTPS). |
| Sign in with | SFTP: password, private key file (with an optional passphrase), or the SSH agent (Pageant or the OpenSSH Authentication Agent on Windows, SSH_AUTH_SOCK on macOS). FTP and FTPS: password. |
| Root folder | The server folder everything is relative to; empty for the login folder. For a folder server: the absolute local folder. |
| Path mappings | Local folder (project-relative, empty for the root) → remote folder (relative to the root, or absolute with a leading /). The longest matching local folder wins. Without mappings the project root goes to the root. Files outside every mapping are skipped. |
| Excluded paths | One per line. A path excludes itself and everything below it (var/cache); a pattern with * or ? matches file and folder names (*.log). .git, .svn and .hg are never deployed. |
| Upload on save | Off by default. When on, every saved file that maps to the server is uploaded in the background. |
The configuration lives in Lutra's config directory (deployment/<project-id>.json), not in the project, and never contains a password.
Passwords and passphrases
- They are stored only in the operating system's keychain: the Windows Credential Manager or the macOS Keychain, under the service "Lutra Deployment".
- Lutra never writes them to a file, a log, the recovery journal, an event, MCP or control-channel output, or an error message. The password field in the dialog is write-only: after Save it empties again and says "Stored in the system keychain".
- Removing a server removes its keychain entries.
- Linux has no keychain store yet; there, use the SSH agent or a key without a passphrase.
Host keys (SFTP)
On the first connection, Test Connection shows the server's key fingerprint (ssh-ed25519 SHA256:…). Compare it with the one from the server's administrator, then choose Trust and Connect. Trusted keys are kept in Lutra's own known-hosts file (deployment/known_hosts in the config directory); ~/.ssh/known_hosts is neither read nor changed.
If the key later differs, Lutra refuses to connect and says so: someone may be intercepting the connection. Only if you know the server was reinstalled, test the connection and choose Replace the Trusted Key.
Uploads and downloads never ask about a key; they fail with a message pointing to Test Connection.
Upload and download
- Project tree: right-click a file or folder › Upload to Server / Download from Server (default server).
- Tools › Deployment: Upload Current File, Download Current File, Upload Project, Test Connection, Deployment Log.
- The same actions are in the command palette. Lutra assigns no default shortcuts; bind them in the keymap.
- Uploads send what is on disk; save first. Downloads replace the local files.
- While a job runs, the status bar shows it with a Cancel button. One job runs at a time; uploads on save wait for the running one.
- Every file, skip and error goes to the Deployment log in the bottom panel (newest 1,000 lines). A failing file is logged and the job goes on; a lost connection or a refused sign-in stops it. Each error says what to do.
For agents and scripts
The deploy.* engine commands (deploy.servers, deploy.saveServer, deploy.setSecret, deploy.testConnection, deploy.trustHostKey, deploy.upload, deploy.download, deploy.cancel, deploy.log, …) work over the control channel and MCP like every command; see docs/architecture.md › Deployment. Their results never contain a secret.
Not yet (D2)
A remote file browser, opening and editing remote files, compare with the server, and sync with a preview.