Skip to main content
Choose the install method that matches your environment:
  • npm — recommended. One command on any machine with Node.js.
  • Linux packages — .deb, .rpm, and .apk built for Debian/Ubuntu, RHEL/Fedora, and Alpine. No Node.js needed.
  • Prebuilt tarball — a portable .tar.gz you can drop onto any Linux or macOS server. No Node.js needed.
  • From source with Node.js — for development or when you need to build a target that is not published.
All methods produce the same gentic CLI. After installing, follow the Git setup below, then configure credentials only for the agent providers this host will run. Options B and C ship a standalone executable compiled with Bun — a single binary plus vendored agent sidecars, with no runtime dependencies at all. Reach for them when the target machine has no Node.js and you don’t want to install one. Supported platforms The CLI is published to npm as gentic-cli on every release. It requires Node.js 20.19 or newer on the machine, and works anywhere npm does — including platforms with no prebuilt binary.
1

Install globally

The package name is gentic-cli; the command it installs is gentic.
2

Verify

3

Upgrade later

Upgrading in place keeps the path an installed service points at, so a running gentic service picks up the new version on its next restart.
The install brings the ACP agent runtimes the host spawns, so — as with every other option — the only things left are Git access and the agent CLIs and credentials. Run gentic doctor to see what is still missing.

​
Option B: Linux packages (.deb, .rpm, .apk)

Every release publishes native Linux packages for x86-64 and ARM64 alongside the tarballs, built from the same binary. Use these if you manage your fleet with apt, dnf/yum, or apk. The packages install the binary to /usr/lib/gentic/gentic with its vendor/ sidecars next to it, and expose gentic on PATH via /usr/bin/gentic.
Replace <version> with the release version (e.g. 0.4.2) and linux-x64 with linux-arm64 on ARM64 hosts.
The exact filenames — including the version — are listed on the Releases page. Checksums for every artifact are published in checksums.txt on the same release.

​
Option C: Prebuilt tarball

If you don’t want a package manager to own the binary — for example, when deploying into a container image or a locked-down server — download the raw tarball and extract it yourself.
The archive contains the gentic binary plus vendor sidecars (vendor/claude-agent-acp/ and vendor/codex-acp/) that are spawned as child processes at runtime. Always keep the entire extracted directory together — do not copy gentic on its own.
Release archives are named gentic-<version>-<os>-<arch>.tar.gz, e.g. gentic-0.4.2-linux-x64.tar.gz.
1

Download the archive for your platform

Substitute <version> with the release version and linux-x64 with your platform slug (linux-arm64, darwin-x64, or darwin-arm64).
2

Verify the checksum

3

Extract the archive

You will see the gentic binary and the vendor/ directory alongside it.
4

Run the host

Set your credentials in the environment and start the host:
For production use, run gentic start instead to install a managed system service. See Service Management.
macOS binaries are not code-signed or notarized. On first run, Gatekeeper will block execution with a security warning. To allow it, open System Settings → Privacy & Security and click Allow Anyway, or run xattr -dr com.apple.quarantine ./gentic from the terminal. This applies to the binaries in Options B and C; the npm package (Option A) runs gentic itself through your own Node.js install.

​
Option D: From source with Node.js

Run from source when you need to build a platform that is not published, or when you are developing against the host. Requires Node.js 20 or newer and pnpm 11.9.0 or newer on the machine.

​
Compile your own standalone binary

If you just need a gentic binary for a target that is not in the release matrix, use the build script — you still get the same standalone output as Option C, without needing Node.js on the deployment server.
1

Install dependencies from the repository root

2

Run the build script

Pass the Bun compile target and the output directory as arguments:
Valid targets are bun-linux-x64, bun-linux-arm64, bun-darwin-x64, and bun-darwin-arm64.
3

Copy the output directory to your server

​
Run directly from source

1

Clone or upload the repository to the server

2

Install dependencies

3

Build the agent package

4

Start the host

This runs gentic run in the foreground. For production, use gentic start to install a managed system service instead. See Service Management.

​
Git authentication setup

The host clones repositories using the GIT_REMOTE_BASE value (default: git@github.com:). For a project stored as owner/repo, the host clones git@github.com:owner/repo. You must give the host SSH access to every repository it will clone.
1

Generate a deploy key or use a machine user key

2

Add the public key to each repository

In GitHub, go to Repository → Settings → Deploy keys and add the contents of ~/.ssh/gentic_deploy.pub. Enable Allow write access so the host can push branches for pull requests.
3

Configure SSH to use the key

Add the following to ~/.ssh/config on the server:

​
Agent credentials setup

Gentic hosts can claim issues for any supported agent provider. Install and authenticate both Claude Code and Codex in the host environment before starting the host.

​
Claude Code

Claude Code credentials are managed entirely outside Gentic, the same way you would authenticate Claude Code for any other use. Ensure the credentials are present in the environment where the host process runs. The host picks them up automatically through the Agent Client Protocol sidecar.

​
Codex

1

Install the Codex CLI in the host environment

Follow the Codex installation instructions for your platform.
2

Authenticate Codex

Run codex once interactively to complete authentication before starting the host.
3

Set CODEX_PATH if Codex is not on PATH

If the codex binary is not discoverable via PATH in the host’s environment, set the CODEX_PATH environment variable to its absolute path:
Codex runs default to INITIAL_AGENT_MODE=agent-full-access. You can override this by setting the variable in the host’s environment before starting the service.