Skip to main content
The agent worker ships as a standalone binary compiled with Bun — a single output directory you copy to any Linux or macOS server with no runtime dependencies. If you prefer to manage your own Node.js toolchain, you can also run the worker directly from source. Both methods produce the same gentic CLI. Choose the option that matches your environment, then follow the Git and credentials setup below before starting the worker. The standalone binary includes everything the worker needs to run — no Node.js, pnpm, or node_modules required on the target machine. Every release tagged v* (e.g. v0.0.1) publishes prebuilt archives for all supported targets on GitHub Releases.
The output directory contains the gentic binary plus vendor sidecars — vendor/claude-agent-acp/ and vendor/codex-acp/ — which are spawned as child processes at runtime. Always copy the entire output directory to the target machine, not just the gentic binary itself.
Supported targets
TargetPlatform
bun-linux-x64Linux, x86-64
bun-linux-arm64Linux, ARM64
bun-darwin-x64macOS, Intel
bun-darwin-arm64macOS, Apple Silicon

​
Download a prebuilt release

1

Download the archive for your platform

Go to the GitHub Releases page and download gentic-<target>.tar.gz for your platform, along with checksums.txt to verify the download.
# Example for Linux x86-64
curl -LO https://github.com/kprovorov/gentic/releases/latest/download/gentic-bun-linux-x64.tar.gz
curl -LO https://github.com/kprovorov/gentic/releases/latest/download/checksums.txt
2

Verify the checksum

sha256sum --check --ignore-missing checksums.txt
3

Extract the archive

tar -xzf gentic-bun-linux-x64.tar.gz
You will see the gentic binary and the vendor/ directory alongside it.
4

Run the worker

Set your credentials in the environment and start the worker:
GENTIC_API_URL=https://gentic.chat/api/v1 \
GENTIC_API_KEY=<your-api-key> \
./gentic run
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.

​
Build the binary yourself

If you need a target that differs from the prebuilt release or want full control over the build, compile the binary from source using Bun as a build-time dependency.
1

Install dependencies from the repository root

pnpm install
2

Run the build script

Pass the Bun compile target and the output directory as arguments:
cd apps/gentic
./scripts/build-binary.sh bun-linux-x64 dist/linux-x64
Substitute bun-linux-x64 with any supported target listed above.
3

Copy the output directory to your server

scp -r dist/linux-x64 user@your-server:/opt/gentic

​
Option B: From source with Node.js

Running from source requires Node.js 20 or newer and pnpm 11.9.0 or newer on the server.
1

Clone or upload the repository to the server

git clone git@github.com:kprovorov/gentic.git
cd gentic
2

Install dependencies

pnpm install
3

Build the agent package

pnpm --filter @gentic/gentic build
4

Start the worker

pnpm --filter @gentic/gentic start
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 worker clones repositories using the GIT_REMOTE_BASE value (default: git@github.com:). For a project stored as owner/repo, the worker clones git@github.com:owner/repo. You must give the worker SSH access to every repository it will clone.
1

Generate a deploy key or use a machine user key

ssh-keygen -t ed25519 -C "gentic-worker" -f ~/.ssh/gentic_deploy
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 worker can push branches for pull requests.
3

Configure SSH to use the key

Add the following to ~/.ssh/config on the server:
Host github.com
  IdentityFile ~/.ssh/gentic_deploy
  IdentitiesOnly yes

​
Agent credentials setup

​
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 worker process runs. The worker picks them up automatically through the Agent Client Protocol sidecar.

​
Codex

1

Install the Codex CLI in the worker environment

Follow the Codex installation instructions for your platform.
2

Authenticate Codex

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

Set CODEX_PATH if Codex is not on PATH

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