gentic) that you deploy on a private server or VM. Once running, it continuously polls the Gentic API for issues whose status has been moved to Todo, claims work up to its configured concurrency limit, clones each associated GitHub repository into a local work directory, and drives an AI coding agent — Claude Code or Codex — through the Agent Client Protocol. The default concurrency limit is one issue.
How it works
When you move an issue from Draft to Todo in the Gentic web app, the API adds it to the unclaimedtodo pool. On its next poll cycle, the agent host claims that issue (flipping it to queued), creates a fresh clone of its configured repository, and runs the issue’s assigned agent provider through the Agent Client Protocol. The host streams assistant output back into the issue transcript in real time.
The host does not add hidden publishing instructions to the agent session. After a successful turn, it records whether that turn produced unpublished changes. If Create PR automatically is enabled and no pull request exists, the API atomically adds one visible Gentic-authored publishing message for the active run. The host continues the same ACP session to process it. Host restarts and concurrent calls reuse that request instead of creating a duplicate.
Unchanged, failed, held, usage-limited, cancelled, and interrupted runs do not trigger automatic publishing. Once the agent goes quiet, the run resolves to ready-for-review if a pull request was opened or waiting-for-input otherwise. If you send a follow-up message to an issue whose run has already ended, the API returns it to todo and the host resumes the same ACP session — preserving the full conversation context.
For a backward-compatible deployment, apply the database migration first, deploy the web app and API second, and update agent hosts last. The database and non-web API default is
false, so older hosts and existing issues remain opted out until the web/API layer and then the host understand the new fields.Deployment options
You can deploy the agent host in three ways. Choose the option that fits your server environment best.npm
npm install -g gentic-cli on any machine with Node.js 20.19+. Recommended for most servers.Standalone Binary
Download a prebuilt, self-contained binary — or a
.deb/.rpm/.apk — from GitHub Releases. No Node.js required on the target machine.From Source (Node.js)
Clone the repository, install dependencies with pnpm, and run the host with
pnpm --filter @gentic/gentic start. Best for development.Prerequisites
Review these requirements before installing the agent host. Which prerequisites apply to you depends on your chosen deployment method.Node.js 20.19+
Required for the npm install and when running from source (which also needs pnpm 11.9.0+). Not needed when using the standalone binary.
Bun (build-time only)
Required only if you want to compile the standalone binary yourself from source. Not needed on the target machine that runs the binary.
Git & SSH access
The host clones repos over SSH by default. Add an SSH deploy key or machine user key to every repository Gentic will access.
AI agent credentials
Claude Code credentials must be present in the host environment. Codex must be installed and authenticated separately; set
CODEX_PATH if it is not on PATH.Security note
Run the agent host on a private server or VM. It is a background polling process — not a web server. Do not expose it as a public HTTP endpoint. Keep yourGENTIC_HOST_CREDENTIAL and SSH credentials secret and limit access to the machine accordingly.
Next steps
Installation
Install from npm, use a prebuilt binary, or run from source, and set up Git authentication.
Configuration
Configure your host credential, API URL, and other environment variables.
Service Management
Start, stop, and restart the host as a managed system service.