← Docs

Cloning a repository over SSH

Brisal clones private repos over SSH via your SSH agent. No stored credentials; never reads ~/.ssh. See Projects for Remote sources.

Paste the URL

Use either SSH URL form:

  • git@host:org/repo.git
  • ssh://git@host/org/repo.git

In New Project: From Remote (Git), paste URL, Create Project. Public repos: use https://. Rejected: http://, git://, file://.

Requirement: key in reachable agent

An SSH clone needs an authorized key in an agent Brisal can reach.

Check loaded keys:

ssh-add -l

Missing? Load it:

ssh-add ~/.ssh/your-key

“Couldn’t authenticate to the repository”

If ssh-add -l shows your key but clone fails, Brisal uses a different agent than your terminal.

macOS: Finder or Dock launch uses keychain agent. Load key:

ssh-add --apple-use-keychain ~/.ssh/your-key

Persists across logins.

Linux: Brisal uses the agent from its launch environment. If you launch from a terminal, launch Brisal from a shell where ssh-add -l shows your key.

If you launch from a desktop entry or file manager, export your agent socket to the user session first:

systemctl --user import-environment SSH_AUTH_SOCK
dbus-update-activation-environment --systemd SSH_AUTH_SOCK

On Arch Linux with no agent running, create a user ssh-agent service:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/ssh-agent.service <<'EOF'
[Unit]
Description=SSH authentication agent

[Service]
Type=simple
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now ssh-agent.service
export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"
ssh-add ~/.ssh/your-key

For desktop launches after creating that service, import the socket as shown above.

Re-pinning host key

First clone: Brisal pins host key in known_hosts.toml at app data root (with system/, workspaces/).

If host key changes, clone fails: “The server’s SSH host key has changed since you last connected.”

Re-pin: delete host line from known_hosts.toml. Next clone pins new key. See Config files.

  • Projects — Remote sources vs Scratch/Local.