# Deployment > **Status:** Deployment v1 (C9 D1, owner decision D27): servers per project, upload, download, upload on save, test connection, host keys, Deployment log. v2 (C9 D2): Remote Host browser, compare with the server, sync with a preview, save before upload · **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/.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. - An upload first saves the open, unsaved files it covers, so the server gets what the editor shows. 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. ## Remote Host **Tools › Deployment › Remote Host** opens the server's folders in the bottom panel (the default server; choose another in the toolbar). Paths are relative to the server's root folder; the browser never leaves it. - Click a folder to expand it, a file to open it. Files open **read-only**; **Edit** makes the text editable and **Upload** writes it back. Files that are not text, or larger than 4 MiB, are not shown. - **Rename** and **Delete on Server** are on each row; **New Folder** goes into the selected folder. Delete always asks first, names what goes (a folder with everything inside it), and only the red button deletes. The root folder cannot be deleted. ## Compare and sync - **Compare with Server** on a file (project tree, or Tools › Deployment › Compare Current File with Server) opens the diff viewer: the server's copy on the left (read-only), your working copy on the right (editable as usual). - On a folder, or **Sync Project with Server…**, Lutra lists every file that differs: only in the project, only on the server, or changed (sizes first, then contents up to 8 MiB per file; larger files of equal size count as equal). Excluded and unmapped files are left out. - The preview selects the uploads (new and changed files). Files only on the server would be **deleted on the server**; they are never selected for you, and once you select one, Sync stays disabled until you tick "I understand that … files will be deleted on the server". Sync goes from the project to the server only; to take a server change into the project, use Download. ## For agents and scripts The `deploy.*` engine commands (`deploy.servers`, `deploy.saveServer`, `deploy.setSecret`, `deploy.testConnection`, `deploy.trustHostKey`, `deploy.upload`, `deploy.download`, `deploy.browse`, `deploy.readRemote`, `deploy.writeRemote`, `deploy.renameRemote`, `deploy.mkdirRemote`, `deploy.deleteRemote`, `deploy.compare`, `deploy.sync`, `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. `deploy.deleteRemote` refuses without `confirm: true`, and `deploy.sync` refuses deletions without `confirmDelete: true`: an agent must have asked the user. ## Not yet - Remote files open in the Remote Host viewer, not as editor tabs with highlighting. - FTPS accepts only certificates the system trusts; servers with a self-signed certificate cannot be pinned yet. - Linux has no keychain store yet.