Everlock One server for your digital life

Documentation

Last updated: 2026-09-27

Getting started: Git backend

This guide walks through a local first run of Everlock's Git backend:

  • start Everlock with the SSH frontend and the Git backend
  • create a user — the bootstrap admin — through the admin SSH console
  • create a repository
  • clone it, commit, and push over SSH
  • pull it back again

Everlock speaks the normal Git smart protocol over SSH, so you use a stock git client throughout — Everlock handles storage, auth, and ref updates on its side.

1. Start Everlock with Git enabled

For a local first pass, start Everlock with:

  • the SSH frontend enabled (Git and the admin console both ride on it)
  • the admin SSH backend enabled
  • the Git backend enabled
everlock serve \
  --frontend-ssh \
  --frontend-ssh-listen 127.0.0.1:2222 \
  --backend-admin-ssh \
  --backend-git-ssh \
  --admin-user admin \
  --admin-password change-me

What this does:

  • starts the SSH frontend on 127.0.0.1:2222
  • enables the admin REPL and the Git backend behind it
  • bootstraps an admin user for the SSH admin console

The same SSH port serves both: an interactive login lands you in the admin console, while a git command on the same connection is dispatched to the Git backend.

2. Open the admin console

Connect over SSH:

ssh -p 2222 admin@localhost

Enter the bootstrap password:

change-me

You should land in the Everlock admin REPL:

Everlock Admin
>

3. Create a repository

/git repo create my-project

Expected output:

  created repository 'my-project'
  owner: admin (*/git/my-project)

Two things happen at once: the bare repository is created, and you — the creating user — are granted owner on the access path */git/my-project. That grant covers the repository across every transport — SSH and HTTP alike.

List what you can see:

/git repo list

  my-project                   ssh://admin@localhost:2222/my-project.git

4. Clone over SSH

From a normal shell (not the admin console), clone the new repository:

git clone ssh://admin@localhost:2222/my-project.git

Git prompts for the admin password (change-me). The clone produces an ordinary local repository — every standard Git operation works against it.

The SSH URL breaks down as:

ssh://admin@localhost:2222/my-project.git
      ─────  ─────────  ────  ────────── ────
      user   host       port  repo name  suffix

The .git suffix is the bare-repository convention (as on GitHub and GitLab); Everlock accepts the clone URL with or without it.

5. Make a commit and push

cd my-project
echo "# My project" > README.md
git add README.md
git commit -m "initial commit"
git push

The push output follows the standard Git protocol:

Enumerating objects: 3, done.
Writing objects: 100% (3/3), 230 bytes | 230.00 KiB/s, done.
To ssh://admin@localhost:2222/my-project.git
 * [new branch]      main -> main

Everlock stores the incoming pack as a compressed bundle and applies the ref update atomically — it does not explode the pack into loose objects.

6. Pull it back

Confirm the server really has your commit:

git ls-remote ssh://admin@localhost:2222/my-project.git

Or clone a fresh copy into another directory:

git clone ssh://admin@localhost:2222/my-project.git my-project-check

If the second clone contains your README.md, the Git backend is working end to end:

  • the SSH frontend accepted and authenticated the connection
  • the request was dispatched to the Git backend
  • the pack was stored and the ref updated
  • access was checked against your */git/my-project grant

7. Give someone else access

Add a second user and grant them access to the repository:

/users create bob change-me
/users grant bob */git/my-project reader

Roles are reader (clone), writer (clone + push), and owner (clone + push

  • delete). Use the */git/<name> path so the grant survives the arrival of the HTTP frontend. Bob then clones with his own credentials:
git clone ssh://bob@localhost:2222/my-project.git

See Access control and grants for the full model, including groups.

8. Avoid the password prompt

Password auth is fine for a first run, but for day-to-day use register an SSH public key so Git stops prompting. From the admin console:

/users ssh-keys create admin "ssh-ed25519 AAAA... you@host"

Paste the contents of your public key (e.g. ~/.ssh/id_ed25519.pub). After that, clones and pushes authenticate with your key — no password.

9. Operator caveats

  • Repositories can be managed through /git repo ... in the admin SSH console.
  • Repository names are lowercase letters, digits, and hyphens only — they appear in SSH URLs and on-disk paths.
  • Repositories are stored as standard bare Git repositories; with shell access to the data directory they are readable with plain git or gix.
  • Maintenance runs itself: the daily git.gc job prunes unreachable objects (crash orphans, rewound branches) older than a grace window, in-process and safe against a live repo. See Managing repositories.
  • Repositories are also reachable over HTTPS: /backends enable git-http plus a host in git.http.vhost serves the smart HTTP protocol and a web UI for browsing trees, history and diffs on the same vhost.
  • A git push is also how content reaches the site backend: site stores are ordinary Git repositories the site reads from directly.
git ssh getting-started