Prerequisites

Required#

glci drives Docker by default, and also supports Podman as a drop-in container engine. Set the engine explicitly with [docker] engine = "podman" in ~/.glci/config.toml — this is a global setting and is ignored in a project .glciconfig.toml. When the engine is unset, glci uses Docker if reachable and otherwise falls back to Podman. See Configuration > Config files.

Podman must be exposing its Docker-compatible API socket (glci mounts it into runner containers). Start it with systemctl --user enable --now podman.socket (rootless), sudo systemctl enable --now podman.socket (rootful), or podman machine start (macOS/Windows). Run glci doctor to verify both the engine and its API socket.

On macOS and Windows Podman runs inside a VM, so the API socket lives inside that VM and cannot be dialed from the host: glci doctor reports the socket as “cannot verify from host”, which is expected and does not fail the check. glci picks up the machine’s ssh:// endpoint from podman system connection list (exporting CONTAINER_HOST and CONTAINER_SSHKEY) and mounts the socket path that connection reports. Use podman machine list to confirm the machine is running.

The same applies on Linux when the resolved Podman endpoint is not a local unix:// path — CONTAINER_HOST, or failing that the default podman system connection, pointing at ssh:// or tcp://. The socket is on the far side, so doctor reports “cannot verify from host” rather than failing a perfectly healthy remote Podman.

No gitlab-runner binary is needed on the host – glci runs the official gitlab/gitlab-runner Docker image automatically.

Optional#

GitLab token#

A token is needed for include: project:, include: component:, CI/CD variables, and cross-project triggers. Token resolution order:

1. --token flag
2. GITLAB_TOKEN or GITLAB_PRIVATE_TOKEN environment variable
3. [gitlab] token in .glciconfig.toml / ~/.glci/config.toml
4. glab auth credential-helper (if glab is installed and authenticated via glab auth login) – supports keyring, OAuth2 refresh, and PAT/CI tokens
5. Direct read of ~/.config/glab-cli/config.yml – legacy fallback

Verify your token source with glci config --gitlab.

If the instance URL comes from a project .glciconfig.toml, only --token and a [gitlab] token in that same project file are used — glci does not send environment, glab, or ~/.glci/config.toml credentials to a host the repository chose. See [gitlab] url in a project config.

Platform support#

On macOS, Colima (colima start) is recommended. It exposes the Docker socket at the default location with no extra configuration. For Podman on macOS or Windows, run podman machine start; the default machine (rootless inside the VM) is supported as-is. Pipelines that need Docker-in-Docker still want a rootful machine — see Troubleshooting > Podman.

On Linux, ensure your user is in the docker group (or use rootless Docker). For Podman, enable its API socket (systemctl --user enable --now podman.socket for rootless, sudo systemctl enable --now podman.socket for rootful).

Port requirements#

glci publishes the mock server on port 39741 (default) of the Docker host. This port must be available (not used by another process) on every Docker host where glci runs. CI job containers reach the mock server through this port via Docker’s host-gateway mechanism.

The port is configurable via mock_server_port in ~/.glci/config.toml:

[network]
mock_server_port = 39741   # default

Note: Changing this port requires a full daemon restart (glci daemon stop && glci daemon start). A running daemon will continue using the port it started with.

If the port is already in use, glci will fail to start the mock server. See Troubleshooting > Port conflicts for diagnosis steps.

Remote Docker daemons#

Remote Docker daemons (DOCKER_HOST=tcp://..., Docker contexts, cloud-hosted Docker) are supported. glci detects the endpoint in this order:

1. [docker] host in ~/.glci/config.toml
2. DOCKER_HOST environment variable
3. Active Docker context (docker context use or DOCKER_CONTEXT)
4. Default Docker socket

For remote daemons, glci uses a docker exec transport instead of bind mounts, so no shared filesystem is required between the glci host and the Docker daemon.

[docker]
host = "tcp://remote-host:2375"   # or "ssh://remote-host"

Or per shell, without touching the config — an exported DOCKER_HOST beats the active context, just as it does for the docker CLI:

DOCKER_HOST=tcp://remote-host:2375 glci run

The daemon resolves the endpoint once at startup and is shared by every project, so switching endpoints needs glci daemon stop (it re-starts on the next command). glci warns when your shell selects an endpoint the running daemon is not using rather than restarting it behind your back — see Endpoint changes and the shared daemon. glci daemon status reports the endpoint currently in use and where it came from.

Note: Use glci system prune instead of docker system prune on shared remote hosts – it only cleans glci-specific resources.