Vetrix Docs

Git Protocol

Vetrix supports both SSH and HTTPS for Git operations.

SSH

Key types

Supported key types: ed25519 (recommended), ecdsa, rsa (minimum 2048-bit).

Generate a new key if needed:

ssh-keygen -t ed25519 -C "you@example.com"

Adding your key

  1. Copy your public key: cat ~/.ssh/id_ed25519.pub
  2. Go to Settings → SSH Keys → Add Key
  3. Paste the key and give it a label

SSH config

If the server runs on a non-standard port (default: 22), add an entry to ~/.ssh/config:

Host vetrix
    HostName <vetrix-host>
    User git
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Then use git@vetrix:<owner>/<repo>.git as the remote URL.

SSH URL format

git@<vetrix-host>:<owner>/<repo>.git

Testing connectivity

ssh -T git@<vetrix-host>
# Welcome to Vetrix, <username>!

HTTPS

Personal access tokens

HTTPS authentication requires a personal access token (PAT) — Vetrix does not accept your account password for Git operations. A JWT session token is also accepted in the Authorization: Bearer … header.

Required scope for push: PATs must carry the repo:write (or repo:admin) scope to be accepted on git push. Tokens with only repo:read receive 403 Forbidden on push attempts. Expired tokens receive 401 Unauthorized.

Generate a token at Settings → Access Tokens:

curl -X POST https://<vetrix-host>/api/v1/user/tokens \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "expires_in_days": 90}'

The token is shown once only. Store it in your credential helper.

Credential storage

macOS Keychain:

git config --global credential.helper osxkeychain

Linux (libsecret):

git config --global credential.helper /usr/lib/git-core/git-credential-libsecret

Windows Credential Manager:

git config --global credential.helper manager

After configuring a helper, Git will prompt once and cache the credentials.

HTTPS URL format

https://<vetrix-host>/<owner>/<repo>.git

When prompted:

  • Username: your Vetrix username
  • Password: your personal access token

Git credential environment variables

For CI environments, pass credentials inline:

git clone https://<username>:<token>@<vetrix-host>/<owner>/<repo>.git

Or set via environment:

export GIT_ASKPASS=echo
export GIT_USERNAME=<username>
export GIT_PASSWORD=<token>

SSH server configuration (admins)

The SSH server binds to the address and port set by git.ssh_listen in vetrix.toml (default 0.0.0.0:22). The host key is stored at git.ssh_host_key_path (default ./data/ssh_host_ed25519_key).

Generate a host key once during initial setup:

ssh-keygen -t ed25519 -f ./data/ssh_host_ed25519_key -N ""

Relevant config:

[git]
ssh_listen        = "0.0.0.0:22"
ssh_host_key_path = "/data/ssh_host_ed25519_key"
repo_root         = "/data/repos"

Firewall note: port 22 is typically reserved for system SSH. Running Vetrix on port 2222 and adding the ~/.ssh/config block above is a common setup on shared hosts.