SSH access to instances

How SSH access works

Each instance gets its own SSH accounts on its server. When you connect with your registered key, you can only reach that instance: forward its ports to your computer, or open a shell inside its Odoo or PostgreSQL container. You never get a login on the server itself.

Three things must be in place:

• User SSH Access is switched on for the server the instance runs on.
• You have registered at least one SSH key on your account.
• You hold the right permissions on the project (in a workspace).

Switching on SSH access for a server

This is done once per server, by someone who can edit the server.

1. Open the Servers page.
2. Open the server's Actions menu and click Edit Server.
3. Turn on User SSH Access. This lets users with a registered SSH key tunnel to the server's instances and shell into their containers. Your own SSH users and root keys on the server are not touched.
4. Click Save Changes.

The server picks up the change on its next sync, usually within five minutes.

Adding your SSH key

1. Open Settings and go to the Security tab.
2. In the SSH Keys card, click Add SSH Key.
3. Enter a Name for the key (for example, Work laptop).
4. In Public key, paste the contents of your .pub file, for example ~/.ssh/id_ed25519.pub. Never paste a private key.
5. Click Add Key.

The key appears in the list with its type and fingerprint. Servers install new keys within about five minutes. A key reaches only what your permissions already allow.

If you do not have a key yet, create one on your computer with your usual SSH tool (for example ssh-keygen), then paste the contents of the .pub file it creates.

Disabling or removing a key

1. Open Settings and go to the Security tab.
2. In the SSH Keys card, find the key.
3. Click Disable to stop using it for now (it shows as "disabled", and Enable turns it back on), or click Remove and confirm to delete it.

Servers stop accepting a disabled or removed key within a few minutes.

Finding your connection commands

1. Open the instance in the Console and click the Access tab.
2. Scroll to the SSH Access card.
3. Click a command to copy it, then paste it into a terminal on your computer.

The server address in the commands is partly masked on screen, but the copied command contains the real address. If the server uses an SSH port other than 22, the commands already include it.

Instead of commands, the card may show a message:

• "SSH access is not enabled on this server.": turn on User SSH Access for the server, as described above.
• A link "Add a key": you have no SSH key on your account yet.
• "Setting up, nearly there.": your key is not on the server yet. Reload the page after a few minutes.
• "This server could not finish setting up SSH access.": the server reported the error shown under the message. Open a support ticket if it does not clear.
• "Your permissions on this instance do not include SSH access.": ask a workspace admin for the permissions listed below.

Opening a tunnel to the database or Odoo

The Tunnel command forwards the instance's ports to your own computer. It has this shape:

ssh -N -L 15432:127.0.0.1:<postgres-port> -L 18069:127.0.0.1:<odoo-port> <account>@<server>

1. Copy the Tunnel command from the SSH Access card and run it in a terminal. It shows no output while the tunnel is open.
2. Read the line under the command to see which local port leads where, for example PostgreSQL on 127.0.0.1:15432 and Odoo on 127.0.0.1:18069. Longpolling and IDE ports appear too when you have access to them.
3. Point your database client at 127.0.0.1 and the local PostgreSQL port, using the database name and user from the Database Connection card.
4. Press Ctrl+C in the terminal to close the tunnel.

The local ports are chosen so they do not clash with an Odoo or PostgreSQL already running on your computer.

Opening a shell in a container

The card shows Shell in the Odoo container and Shell in the PostgreSQL container commands, each with its own account:

ssh -t <account>@<server>

1. Copy the command for the container you need.
2. Run it in a terminal. You land in a shell inside that container.
3. Type exit to leave.

On a high availability replica, the PostgreSQL shell is a read-only standby. An app node has no PostgreSQL shell, because it has no database of its own.

Copying files in or out

The Copy files in or out example shows scp and rsync commands against the Odoo container account:

scp ./file <account>@<server>:/tmp/
rsync -az ./addons/ <account>@<server>:/mnt/extra-addons/

Replace the local paths with your own. scp, rsync, sftp and remote commands all run inside the Odoo container.

Connecting VS Code (Remote-SSH)

1. Copy the VS Code Remote-SSH block from the SSH Access card. It is a Host entry whose name ends in -code.
2. Paste it into the ~/.ssh/config file on your computer.
3. Replace ~/.ssh/your_key with the path to your private key, in both places it appears.
4. In VS Code, run "Remote-SSH: Connect to Host" and pick the host name shown under the block.

VS Code then opens a session inside the Odoo container.

Permissions

In a workspace, what the card offers follows your permissions on the project:

• "SSH & database": the tunnel to the Odoo, longpolling and PostgreSQL ports.
• "IDE": the Odoo container shell, file copying, VS Code, and the IDE port in the tunnel.
• Both: the PostgreSQL container shell.

Workspace owners have all of these. Adding or removing a key, or a permission change, takes effect on the server within about five minutes. See Member permissions and resource access.

Related: Web IDE and remote access, Adding a server, A member cannot see or use a resource, Two-factor authentication (2FA).

If you get stuck, open a support ticket from the Tickets page or the chat widget.