Skip to content

04-ssh.md

Latest commit

 

History

History
259 lines (182 loc) · 5.92 KB

04-ssh.md

File metadata and controls

259 lines (182 loc) · 5.92 KB
title SSH access
description Grant agents SSH access to specific hosts without exposing private keys.
keywords
moat
ssh
git
github
gitlab
private keys

SSH access

This guide covers granting agents SSH access to specific hosts. Moat proxies SSH agent requests so agents can authenticate via SSH without your private keys entering the container.

How it works

When you grant SSH access:

  1. Moat starts an SSH agent proxy inside the container
  2. The proxy connects to your host's SSH agent (SSH_AUTH_SOCK)
  3. Key listing and signing requests are forwarded to your real SSH agent
  4. Only keys mapped to granted hosts are visible to the container
  5. Private keys never enter the container—only signature requests are proxied

Prerequisites

Your SSH agent must be running with keys loaded:

# Check if SSH agent is running
$ echo $SSH_AUTH_SOCK

# If not set, start the agent
$ eval "$(ssh-agent -s)"

# Add your key
$ ssh-add ~/.ssh/id_ed25519

List loaded keys:

$ ssh-add -l

256 SHA256:abc123... user@host (ED25519)

Granting SSH access

Grant access to a specific host:

$ moat grant ssh --host github.com

Using key: user@host (SHA256:abc123...)
Granted SSH access to github.com

Grant access to multiple hosts:

$ moat grant ssh --host github.com
$ moat grant ssh --host gitlab.com
$ moat grant ssh --host bitbucket.org

Using SSH in runs

Via CLI flag

$ moat run --grant ssh:github.com -- git clone git@github.com:org/repo.git

Via moat.yaml

grants:
  - ssh:github.com
  - ssh:gitlab.com

Then:

$ moat run -- git clone git@github.com:org/repo.git

Example: Clone and work with a private repository

  1. Ensure SSH agent is running with your key:

    $ ssh-add -l

  2. Grant SSH access:

    $ moat grant ssh --host github.com

  3. Clone a private repository:

    $ moat run --grant ssh:github.com -- git clone git@github.com:my-org/private-repo.git

Cloning into 'private-repo'...
remote: Enumerating objects: 1234, done.
remote: Counting objects: 100% (1234/1234), done.
...

  4. Work with the repository:

    $ moat run --grant ssh:github.com -- sh -c "cd private-repo && git pull"

Combining SSH and HTTPS credentials

For workflows that use both SSH (for git) and HTTPS (for APIs):

grants:
  - github         # HTTPS API access
  - ssh:github.com # SSH git access

When both github and ssh:github.com grants are active, Moat automatically configures git to use SSH instead of HTTPS for github.com. This means git clone https://github.com/org/repo.git is transparently rewritten to use git@github.com:org/repo.git. This avoids authentication issues caused by the proxy's TLS interception conflicting with git's HTTPS transport.

To disable the rewrite and use HTTPS for GitHub even when an SSH grant is active, set MOAT_GIT_SSH_GITHUB=0 in moat.yaml under env: or pass it via --env.

$ moat run -- sh -c "
  # This uses SSH under the hood (automatic rewrite)
  git clone https://github.com/org/repo.git
  cd repo
  # Use GitHub API via HTTPS (token injected)
  curl -s https://api.github.com/repos/org/repo/pulls
"

Host-specific key mapping

SSH grants are host-specific. Each grant maps your SSH key to one host:

$ moat grant ssh --host github.com
$ moat grant ssh --host gitlab.com

Inside the container, only keys for granted hosts are visible:

# With only github.com granted:
$ moat run --grant ssh:github.com -- ssh -T git@github.com
Hi user! You've successfully authenticated...

$ moat run --grant ssh:github.com -- ssh -T git@gitlab.com
Permission denied (publickey).

Interactive SSH sessions

For interactive SSH (not just git), use interactive mode:

$ moat run -i --grant ssh:myserver.com -- ssh user@myserver.com

Revoking SSH access

SSH credentials are stored separately from other grants. To remove SSH access for a host, re-grant it to overwrite, or delete the SSH mapping file directly:

$ rm ~/.moat/credentials/ssh.json

This removes all SSH host mappings. To remove a single host, edit the file and delete the corresponding entry.

Troubleshooting

"SSH_AUTH_SOCK not set"

Your SSH agent is not running. Start it:

$ eval "$(ssh-agent -s)"
$ ssh-add ~/.ssh/id_ed25519

Add to your shell profile to start automatically.

"Permission denied (publickey)"

  1. Verify the key is loaded:

    $ ssh-add -l

  2. Verify the host is granted:

    $ moat run --grant ssh:github.com -- env | grep SSH

  3. Test SSH from outside Moat:

    $ ssh -T git@github.com

"Could not read from remote repository"

The SSH grant may be missing. Add it:

$ moat run --grant ssh:github.com -- git clone git@github.com:org/repo.git

Or in moat.yaml:

grants:
  - ssh:github.com

Key not being used

If you have multiple keys, the SSH agent proxy uses the first key that was loaded. Load your preferred key first:

$ ssh-add ~/.ssh/id_ed25519_github
$ ssh-add ~/.ssh/id_ed25519_gitlab

Security considerations

What this protects:

  • Private keys never enter the container filesystem
  • Keys are only usable for granted hosts
  • Signing operations are logged in the audit trail

What this does not protect:

  • A malicious agent could make any git operation on granted hosts
  • The agent has full access to repositories it can clone
  • Commits are made with whatever git identity is configured

Configure git identity in your moat.yaml if needed:

env:
  GIT_AUTHOR_NAME: "My Agent"
  GIT_AUTHOR_EMAIL: "agent@example.com"
  GIT_COMMITTER_NAME: "My Agent"
  GIT_COMMITTER_EMAIL: "agent@example.com"

Related guides