1import{B as e,Ct as t,M as n,R as r,St as i,kt as a,ot as o,st as s}from"./CzsObDY8.js";import"./xihTtKlq.js";import"./C5qy-xbg.js";var c=a({default:()=>p,metadata:()=>l}),l={title:`SFTP File Access`,description:`Access PocketBase instance files over SFTP with Ed25519 SSH keys on macOS, Windows, and Linux`},{title:u,description:d}=l,f=e(`<h1>SFTP File Access</h1> <p>PocketHost provides <strong>SFTP</strong> access to your instance files. This replaces legacy <strong>FTPS</strong> (FTP over TLS on port 21) as the recommended way to upload hooks, migrations, and backups.</p> <p>Authentication is <strong>Ed25519 SSH keys only</strong>. There is no password login on SFTP. Manage keys under <strong><a href="/account/keys">Account â Keys</a></strong> in the dashboard.</p> <blockquote><p><strong>FTPS is deprecated.</strong> Explicit FTPS on port 21 still works with your PocketHost email and password for now, but we are sunsetting it. Use SFTP for all new setups. See the <a href="/blog/sftp-file-access">SFTP announcement</a>.</p></blockquote> <h2>Connection settings</h2> <p>Use these values in every client:</p> <table><thead><tr><th>Setting</th><th>Value</th></tr></thead><tbody><tr><td>Protocol</td><td><strong>SFTP</strong> (SSH File Transfer Protocol). Not FTP, not FTPS.</td></tr><tr><td>Host</td><td><code>ftp.pockethost.io</code></td></tr><tr><td>Port</td><td><code>2222</code></td></tr><tr><td>Username</td><td>Your PocketHost <strong>email address</strong></td></tr><tr><td>Authentication</td><td><strong>SSH private key</strong> (Ed25519)</td></tr><tr><td>Password</td><td>Leave blank (not used)</td></tr></tbody></table> <p>Each SSH key can access <strong>all instances</strong> on your account or a <strong>specific subset</strong> you choose when creating the key.</p> <h2>1. Create an SSH key</h2> <p>Generate an Ed25519 key on your machine (if you do not have one yet):</p> <pre class="hljs language-bash"></pre> <p>Set restrictive permissions on macOS and Linux:</p> <pre class="hljs language-bash"></pre> <p>Open <strong><a href="/account/keys">Account â Keys</a></strong> in the dashboard:</p> <ol><li>Enter a <strong>title</strong> (for example <code>MacBook</code> or <code>GitHub Actions</code>).</li> <li>Paste the contents of <code>~/.ssh/pockethost_ed25519.pub</code> (starts with <code>ssh-ed25519</code>).</li> <li>Choose <strong>all instances</strong> or specific instances, then click <strong>Add SSH key</strong>.</li></ol> <p>Keep the file <strong>without</strong> <code>.pub</code> as your private key. PocketHost stores only the public key.</p> <h2>2. Connect from the command line</h2> <h3>macOS and Linux</h3> <p>OpenSSH ships with macOS and most Linux distributions.</p> <p>One-off connection:</p> <pre class="hljs language-bash"></pre> <p>Add <code>~/.ssh/config</code> for a short alias:</p> <pre class="hljs language-sshconfig"></pre> <p>Then connect with:</p> <pre class="hljs language-bash"></pre> <p>PocketHost exposes <strong>SFTP only</strong>. There is no remote shell, so <code>rsync</code>, <code>scp</code>, and <code>ssh</code> exec do not work.</p> <p>Upload a hook with the <code>sftp</code> client:</p> <pre class="hljs language-bash"></pre> <p>Upload a folder recursively:</p> <pre class="hljs language-bash"></pre> <p>For incremental sync on save, use <a href="/docs/phio">phio</a> or an IDE SFTP extension (see <a href="#3-gui-and-ide-clients">GUI and IDE clients</a>).</p> <h3>Windows</h3> <p><strong>Option A: OpenSSH (Windows 10/11)</strong> â built in. Enable <em>Settings â Apps â Optional features â OpenSSH Client</em> if needed.</p> <p>Save your private key to <code>C:\\Users\\YourName\\.ssh\\pockethost_ed25519</code>.</p> <p>PowerShell or Command Prompt:</p> <pre class="hljs language-powershell"></pre> <p><strong>Option B: PuTTY / PuTTYgen</strong> â if your key is in OpenSSH format, use <strong>Conversions â Import key</strong> in PuTTYgen and save a <code>.ppk</code> file. In PuTTY: Connection â SSH â Auth â Credentials â Private key file. Host <code>ftp.pockethost.io</code>, port <code>2222</code>. PuTTY does not include SFTP file browsing; pair with <strong>WinSCP</strong> (see below) or use OpenSSH <code>sftp</code>.</p> <p><strong>Option C: WSL</strong> â use the macOS/Linux instructions inside your Linux distro.</p> <h2>3. GUI and IDE clients</h2> <p>All clients use the same host, port, username, and private key from <a href="#connection-settings">Connection settings</a>. Protocol must be <strong>SFTP</strong>, not FTP or FTPS.</p> <h3>Cyberduck (macOS, Windows)</h3> <ol><li><strong>Open Connection</strong> â protocol <strong>SFTP (SSH File Transfer Protocol)</strong>.</li> <li>Server: <code>ftp.pockethost.io</code>, Port: <code>2222</code>, Username: your email.</li> <li>Click <strong>SSH Private Key</strong> and choose your private key file (<code>.pem</code> or OpenSSH format without extension).</li> <li>Connect. You land at <code>/</code> with one folder per instance you can access.</li></ol> <h3>FileZilla (macOS, Windows, Linux)</h3> <ol><li><strong>File â Site Manager â New Site</strong>.</li> <li>Protocol: <strong>SFTP - SSH File Transfer Protocol</strong>.</li> <li>Host: <code>ftp.pockethost.io</code>, Port: <code>2222</code>, Logon Type: <strong>
1Key file</strong>.</li> <li>User: your email. Key file: path to your private key.</li> <li>Connect.</li></ol> <h3>WinSCP (Windows)</h3> <ol><li>New session â <strong>SFTP</strong> file protocol.</li> <li>Host: <code>ftp.pockethost.io</code>, Port: <code>2222</code>, User: your email.</li> <li><strong>Advanced â SSH â Authentication</strong> â Private key file (<code>.ppk</code> or OpenSSH; WinSCP can convert on import).</li> <li>Save and login.</li></ol> <h3>Transmit (macOS)</h3> <ol><li>New server â <strong>SFTP</strong>.</li> <li>Address: <code>ftp.pockethost.io:2222</code>, User: your email.</li> <li>Keys tab â import or select your private key.</li> <li>Connect.</li></ol> <h3>VS Code</h3> <p>Install an SFTP extension such as <a href="https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp" rel="nofollow">SFTP</a> or <a href="https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs" rel="nofollow">SSH FS</a>.</p> <p>Example <code>sftp.json</code> (SFTP extension) for syncing <code>pb_hooks</code>:</p> <pre class="hljs language-json"></pre> <p>Adjust <code>remotePath</code> to your instance subdomain and folder.</p> <h3>JetBrains IDEs (IntelliJ, WebStorm, etc.)</h3> <ol><li><strong>Tools â Deployment â Configuration</strong>.</li> <li>Add <strong>SFTP</strong> server: <code>ftp.pockethost.io</code>, port <code>2222</code>, user = email.</li> <li><strong>SSH configuration</strong> â authentication type <strong>Key pair</strong>, private key file = your key.</li> <li>Map local project folder to <code>/your-instance/pb_hooks</code> (or another path).</li></ol> <h2>Instance layout</h2> <p>After login you see a directory for each instance your key can access. Folder names are your instance <strong>subdomains</strong> (for example <code>harvest</code>), not UUIDs. <code>cd</code> into one to reach that instanceâs files on disk.</p> <table><thead><tr><th>Directory</th><th>Description</th></tr></thead><tbody><tr><td><code>pb_hooks</code></td><td>PocketBase JS hooks (<a href="https://pocketbase.io/docs/js-overview/" rel="nofollow">docs</a>)</td></tr><tr><td><code>pb_migrations</code></td><td>Migration files (<a href="https://pocketbase.io/docs/migrations/" rel="nofollow">docs</a>)</td></tr><tr><td><code>pb_public</code></td><td>Static public files</td></tr><tr><td><code>pb_data</code></td><td>Database and uploads (<a href="https://pocketbase.io/docs/going-to-production/" rel="nofollow">docs</a>)</td></tr><tr><td><code>pb_data/backups</code></td><td>PocketBase backups</td></tr><tr><td><code>pb_data/storage</code></td><td>Uploaded files (<a href="https://pocketbase.io/docs/files-handling/" rel="nofollow">docs</a>)</td></tr></tbody></table> <p>These folders are created automatically when the instance starts or when you first connect. You may also see deploy files at the root (<code>package.json</code>, <code>patches/</code>, <code>.ftp-deploy-sync-state.json</code>, etc.) depending on your project.</p> <p><strong>Power off</strong> your instance before modifying <code>pb_data</code> (same rule as the dashboard). Other paths can be edited while the instance is running.</p> <h2>Troubleshooting</h2> <h3>Permission denied (publickey)</h3> <ul><li>Confirm the public key is saved under <strong><a href="/account/keys">Account â Keys</a></strong>.</li> <li>Username must be your <strong>email</strong>, not your instance subdomain.</li> <li>Key must be <strong>Ed25519</strong> (<code>ssh-ed25519</code>).</li> <li>Check the key is allowed to access the instance (all instances vs specific list).</li> <li>Point the client at the correct private key file. If OpenSSH offers the wrong key, add <code>IdentitiesOnly yes</code> under the host in <code>~/.ssh/config</code>.</li></ul> <h3>Connection refused or timeout</h3> <ul><li>Port must be <strong>2222</strong>, not 21 or 22.</li> <li>Host is <code>ftp.pockethost.io</code>, not <code>your-instance.pockethost.io</code>.</li></ul> <h3>Unknown host key on first connect</h3> <p>OpenSSH prompts to verify the server host key the first time you connect. That is expected. Type <code>yes</code> to continue, or add the host to <code>~/.ssh/known_hosts</code> via your clientâs trust flow. GUI clients (Cyberduck, FileZilla, WinSCP) show a similar fingerprint prompt.</p> <h3>OpenSSH post-quantum warning</h3> <p>Recent OpenSSH clients may warn that the connection is not using a post-quantum key exchange algorithm. That refers to transport encryption, not your SSH key. It is safe to connect. We will upgrade when our SFTP stack supports hybrid PQ KEX. Details in the <a href="/blog/sftp-file-access">SFTP blog post</a>.</p> <h2>Legacy FTPS</h2> <p>FTPS on port 21 (explicit TLS, email + password) remains available during the migration period. Do not use it for new projects. It will be removed after a documented sunset peri
1od.</p> <h2>Automated deploy (phio and CI)</h2> <p>For day-to-day development, use <strong><a href="/docs/phio">phio</a></strong> to link a project, watch local files, and sync over SFTP:</p> <pre class="hljs language-bash"></pre> <p>phio manages its own Ed25519 deploy key (labeled <strong><code>Phio</code></strong> under Account â Keys). You do not need a separate key for phio unless you want scoped CI access.</p> <p>For GitHub Actions, either run <strong><code>phio deploy</code></strong> with <code>PHIO_USERNAME</code> / <code>PHIO_PASSWORD</code> secrets (see <a href="/docs/phio">phio CLI</a>), or migrate <a href="https://github.com/SamKirkland/FTP-Deploy-Action" rel="nofollow">SamKirkland/FTP-Deploy-Action</a> from FTPS on port 21 to SFTP on port 2222 with an Ed25519 private key. See <strong><a href="/blog/ftps-sunset">FTPS sunset</a></strong> for the migration timeline.</p>`,1);function p(e){var a=f(),c=s(o(a),20);n(c,()=>`<code class="hljs language-bash">ssh-keygen -t ed25519 -f ~/.ssh/pockethost_ed25519 -C <span class="hljs-string">"[email protected]"</span></code>`,!0),t(c);var l=s(c,4);n(l,()=>`<code class="hljs language-bash"><span class="hljs-built_in">chmod</span> 600 ~/.ssh/pockethost_ed25519</code>`,!0),t(l);var u=s(l,16);n(u,()=>`<code class="hljs language-bash">sftp -i ~/.ssh/pockethost_ed25519 -P 2222 [email protected]@ftp.pockethost.io</code>`,!0),t(u);var d=s(u,4);n(d,()=>`<code class="hljs language-sshconfig">Host pockethost 2 HostName ftp.pockethost.io 3 Port <span class="hljs-number">2222</span> 4 <span class="hljs-keyword">User</span> <span class="hljs-title">you</span>@example.com 5 IdentityFile ~/.ssh/pockethost_ed25519 6 IdentitiesOnly yes</code>`,!0),t(d);var p=s(d,4);n(p,()=>`<code class="hljs language-bash">sftp pockethost</code>`,!0),t(p);var m=s(p,6);n(m,()=>`<code class="hljs language-bash">sftp -i ~/.ssh/pockethost_ed25519 -P 2222 [email protected]@ftp.pockethost.io <<<span class="hljs-string">'EOF'</span> 7<span class="hljs-built_in">cd</span> your-instance/pb_hooks 8put ./myhook.pb.js 9EOF</code>`,!0),t(m);var h=s(m,4);n(h,()=>`<code class="hljs language-bash">sftp -i ~/.ssh/pockethost_ed25519 -P 2222 [email protected]@ftp.pockethost.io <<<span class="hljs-string">'EOF'</span> 10<span class="hljs-built_in">cd</span> your-instance/pb_hooks 11put -r ./pb_hooks 12EOF</code>`,!0),t(h);var g=s(h,12);n(g,()=>`<code class="hljs language-powershell">sftp <span class="hljs-literal">-i</span> C:UsersYourName.sshpockethost_ed25519 <span class="hljs-literal">-P</span> <span class="hljs-number">2222</span> [email protected]@ftp.pockethost.io</code>`,!0),t(g);var _=s(g,32);n(_,()=>`<code class="hljs language-json"><span class="hljs-punctuation">{</span> 13 <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"PocketHost my-instance"</span><span class="hljs-punctuation">,</span> 14 <span class="hljs-attr">"host"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"ftp.pockethost.io"</span><span class="hljs-punctuation">,</span> 15 <span class="hljs-attr">"protocol"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"sftp"</span><span class="hljs-punctuation">,</span> 16 <span class="hljs-attr">"port"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">2222</span><span class="hljs-punctuation">,</span> 17 <span class="hljs-attr">"username"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"[email protected]"</span><span class="hljs-punctuation">,</span> 18 <span class="hljs-attr">"privateKeyPath"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"~/.ssh/pockethost_ed25519"</span><span class="hljs-punctuation">,</span> 19 <span class="hljs-attr">"remotePath"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"/my-instance/pb_hooks"</span><span class="hljs-punctuation">,</span> 20 <span class="hljs-attr">"uploadOnSave"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> 21<span class="hljs-punctuation">}</span></code>`,!0),t(_);var v=s(_,44);n(v,()=>`<code class="hljs language-bash">phio login 22phio <span class="hljs-built_in">link</span> my-instance 23phio dev</code>`,!0),t(v),i(4),r(e,a)}export{p as n,c as t};
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.