01 / PREPARE
Start on Linux with a small dependency set.
The current release is developed for Debian 13 and Linux/POSIX. It needs a C++20 compiler, CMake, Git, curl, zip, and SQLite development headers. There is no Node.js build step and no web framework to install.
sudo apt install build-essential cmake git curl zip libsqlite3-devClone the project repository or open an existing checkout before running the build commands. GitCube creates its persistent data directory on first run.
02 / RUN
Build, test, and open the local server.
Configure a Release build, compile it, run the test suite, and start the executable:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 2
ctest --test-dir build --output-on-failure
./build/gitcubeOpen http://127.0.0.1:9999 on the same machine. GitCube binds to 127.0.0.1 by default and uses port 9999.
By default, persistent data is stored under $XDG_DATA_HOME/gitcube, or ~/.local/share/gitcube when XDG_DATA_HOME is unset. Use --data-dir to choose another location. GitCube locks the data directory so two instances cannot modify the same queue and mirrors at once.
03 / ADD
Bring repositories into your collection.
- Open Add repository.Paste a public HTTP(S) Git URL, one per line. You can submit up to 500 non-empty lines at once.
- Check before adding, if useful.The Check a repository field finds an existing entry without leaving the page.
- Watch the jobs.Each new mirror is queued for cloning. A bare GitHub account URL imports its public repositories through a separate account job.
https://github.com/openeggbert/cnaALL PUBLIC REPOSITORIES IN AN ACCOUNThttps://github.com/openeggbertIf a submitted repository is already known, GitCube skips it. SSH URLs, embedded credentials, and non-HTTP(S) schemes are rejected. GitHub URL variants are normalized so simple spelling differences do not create duplicate entries.
More about imports and mirrors04 / MANAGE
Use the dashboard as a working catalog.
Find a repository
Search by owner, name, host, or description. Filter by state, GitHub account, Git tag, or importance. The list is paginated at 25 repositories per page.
Update and check
Use Fetch or Health on one repository. From the home page, Fetch all and Check all queue eligible bulk work.
Pause future work
Pause a repository to skip new queued and bulk work. Resume it when ready. Pausing does not stop a child process that is already running.
Set importance
Assign 0–3 stars as a personal label. This helps sorting and filtering, but has no effect on scheduling.
On a repository page, choose Files or Commits to browse a branch or tag directly from the bare mirror. The file listing can render a root README; commit pages expose patches and file statistics. The Export controls provide either a files-only snapshot or the complete re-clonable mirror.
GitHub metadata can be refreshed separately. If the public GitHub API is temporarily limited, the metadata job waits while the local mirror remains usable.
05 / INSTALL
Run GitCube as a user service.
For a user-local installation, choose the final prefix during CMake configuration. The generated systemd user unit uses that configured absolute path.
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build-release --parallel 2
cmake --install build-release
systemctl --user daemon-reload
systemctl --user enable --now gitcube.serviceThis places the binary under ~/.local/bin, documentation under ~/.local/share/doc/gitcube, and the unit under ~/.local/share/systemd/user. Installation alone does not enable or start the service; the last command does that explicitly.
The example service uses two Git workers and stores data under ~/.local/share/gitcube. You can customize its limits and options with a systemd user override.
06 / CONFIGURE
Choose the data path, port, and worker count.
| Option | Purpose | Default |
|---|---|---|
--data-dir PATH | Persistent database, mirrors, cache, and temporary files | $XDG_DATA_HOME/gitcube or ~/.local/share/gitcube |
--port PORT | HTTP listening port | 9999 |
--workers COUNT | Concurrent Git job workers | 2 |
--bind ADDRESS | IPv4 listening address | 127.0.0.1 |
--allowed-host H | Additional accepted HTTP Host name; repeatable | None |
A non-loopback bind additionally requires --allow-remote-unauthenticated and an allowed host. Because GitCube has no login or TLS, use it as a local single-user tool unless you have an appropriate authenticated HTTPS layer in front of it.
./build/gitcube --data-dir /mnt/archive/gitcube --port 9999 --workers 407 / RECOVER
Stop safely; let queued work resume.
Use Ctrl+C in the terminal or send SIGTERM. GitCube stops accepting requests and new jobs, gives active Git or curl commands a short chance to finish, then terminates them if needed. Interrupted work is returned to the queue for the next start.
On startup, GitCube removes orphaned partial-clone directories and temporary export files left by a hard crash. The persistent database and completed mirrors remain in the data directory.
How does GitCube keep this reliable?
Read about the job flow, storage layout, and local security boundary.
Under the hood