Grant Espresso Access to Your BYOC Server

If you're running Espresso Cloud in Bring Your Own Cloud (BYOC) mode, your servers stay in your account (AWS EC2, GCP, Azure, bare metal — anywhere). Espresso connects in over SSH to deploy and manage your Docker workloads.

This guide walks you through the one-time setup: create a dedicated espresso user on your server and authorize the public SSH key we share with you.

Time required

About 5 minutes per server.

How it works

1. Espresso generates and shares a public SSH key with you (per workspace).
2. You create a Linux user named espresso on your server.
3. You add our public key to that user's ~/.ssh/authorized_keys.
4. Espresso uses the matching private key to SSH in as espresso and run deployments.

The private key never leaves Espresso's infrastructure. You can revoke access at any time by removing the key — see Revoking access.

Prerequisites

• Ubuntu 20.04 LTS or newer (22.04 / 24.04 recommended)
• Root or sudo access on the server
• The public SSH key shared with you by Espresso (looks like ssh-ed25519 AAAA… espresso@<workspace>)
• Inbound TCP port 22 (or your custom SSH port) reachable from Espresso's egress IPs

Step 1 — Create the espresso user

SSH into your server as your existing admin user, then create the espresso user with a home directory and bash shell:

sudo adduser --disabled-password --gecos "" espresso

--disabled-password means the account has no password login — only the SSH key you authorize in Step 3 will grant access.

Step 2 — Prepare the .ssh directory

Create the SSH directory for the new user with the correct permissions. SSH refuses to use a key file with permissive ownership, so this matters.

sudo -u espresso mkdir -p /home/espresso/.ssh
sudo -u espresso chmod 700 /home/espresso/.ssh
sudo -u espresso touch /home/espresso/.ssh/authorized_keys
sudo -u espresso chmod 600 /home/espresso/.ssh/authorized_keys

Step 3 — Add the Espresso public key

Open the file:

sudo -u espresso nano /home/espresso/.ssh/authorized_keys

Paste the public key Espresso provided you on a single line. It will look something like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… espresso@acme-prod

Save and exit (Ctrl+O, Enter, Ctrl+X in nano).

One key per line

If you add multiple keys (e.g. for staging and production workspaces), each must be on its own line. Do not edit or wrap the key — copy it verbatim.

Step 4 — Grant Docker permissions

Espresso deploys via Docker, so the espresso user needs to run Docker without sudo. Add it to the docker group:

sudo usermod -aG docker espresso

If Docker isn't installed yet:

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker espresso

The group change takes effect on the next SSH session — no reboot needed.

Step 5 — Verify access

From your own machine, you can sanity-check the SSH config (you won't be able to log in as espresso without the private key — that's expected):

ssh -o BatchMode=yes -o ConnectTimeout=5 espresso@<your-server-ip> echo ok

A response of Permission denied (publickey) is good — it means SSH is reachable, the user exists, and only key-based auth is allowed.

Then click Test connection in your Espresso BYOC dashboard. Espresso will:

1. SSH in as espresso
2. Run docker version
3. Report success or the specific error.

Optional hardening

These are recommended for production servers but not required for Espresso to function.

Restrict the key to specific commands or sources

You can prefix the key in authorized_keys to limit what Espresso can do or where it can connect from:

from="203.0.113.0/24",no-agent-forwarding,no-X11-forwarding ssh-ed25519 AAAA… espresso@acme-prod

Ask your Espresso account team for the current egress CIDR ranges before applying a from= restriction.

Disable password auth server-wide

If you haven't already, disable password-based SSH for all users:

sudo sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl reload ssh

Revoking access

To revoke Espresso's access at any time:

sudo -u espresso sed -i '/espresso@<workspace>/d' /home/espresso/.ssh/authorized_keys

Or, to remove the user entirely:

sudo deluser --remove-home espresso
sudo gpasswd -d espresso docker 2>/dev/null || true

Troubleshooting

Symptom	Likely cause	Fix
Permission denied (publickey) from Espresso	Key not in authorized_keys, or wrong file permissions	Re-run Step 2 — ~/.ssh must be 700, authorized_keys must be 600, both owned by espresso
docker: command not found in Espresso logs	Docker not installed	Run the install snippet in Step 4
permission denied while trying to connect to the Docker daemon socket	espresso user not in docker group, or session predates the group change	sudo usermod -aG docker espresso and reconnect
Connection times out	Firewall / security group blocks port 22 from Espresso egress IPs	Open inbound 22 from Espresso's egress ranges
Host key verification failed	Server reinstalled with a new host key	Acknowledge the new fingerprint in your Espresso BYOC dashboard

Need help? Reach out at support@espresso.cloud with your workspace name and the server's hostname or IP.