Skip to main content
The primary way to configure the agent host is with gentic host connect <code>, which exchanges a single-use enrollment code for a stable host id, API URL, and host-specific credential. The CLI saves those values to a persistent config file on disk with owner-only permissions. Environment variables — including a .env file loaded at startup — are the alternative, and are the right choice for containers, CI systems, or local development where you manage secrets through the environment. When the same key appears in both sources, the environment variable takes precedence over the config file.

​
First-run behavior

When you run a gentic command for the first time, the CLI checks whether the host is ready before it continues. This onboarding gate runs for normal host commands, including gentic start and gentic run. It does not run for gentic host connect, gentic onboard, gentic status, gentic doctor, gentic auth, --help, or --version, so you can always connect a host, resume setup, or inspect the CLI without completing onboarding first. If the command is running in an interactive terminal and any required setup is missing, Gentic starts the first-run flow automatically. The flow has four steps:
  1. Gentic auth — verifies that this machine has a stored host id, API URL, and host credential from gentic host connect <code>. This is required.
  2. GitHub CLI — checks that gh is installed and authenticated, and offers to install or run gh auth login when possible. This is required because agents use GitHub CLI access to open pull requests.
  3. Agent CLI — checks both Claude Code and Codex. Both agent CLIs must be installed and authenticated because the host can claim issues for either provider.
  4. Host service — shows a summary and asks whether to enable the background host service with gentic start. This step is optional; you can decline and run gentic start later.
For CI, containers, or other non-interactive environments, bypass the prompts by providing the required settings up front:
You can also connect once, skip local onboarding, and resume setup later:
Non-interactive runs still require gh, Claude Code, and Codex to be installed and authenticated before the host command starts. If any required item is missing, Gentic exits with the unmet requirements instead of prompting.

​
Host Enrollment via CLI

The recommended way to configure credentials is with gentic host connect <code>. This command reads and writes an OS-appropriate config file — for example, ~/.config/gentic/config.json on Linux — that persists across restarts without needing a .env file.
GENTIC_HOST_CREDENTIAL is issued by the enrollment exchange. Do not reuse a shared API key. Losing the config file loses this machine’s host identity; the next enrollment creates a new host instead of reclaiming by hostname.

​
Connect

Generate a host enrollment code in the Gentic web app, then connect this machine:
For a self-hosted or local API, override the initial exchange URL:

​
Check authentication status

Display the currently configured API URL and a masked version of your host credential:

​
Log out

Clear the stored credentials from the config file. Run with --yes (or -y) to skip the confirmation prompt:
Logging out removes the locally stored host registration entries: GENTIC_HOST_ID, GENTIC_HOST_CREDENTIAL, GENTIC_API_URL, and GENTIC_HOST_SETUP_STATE. Other settings stored in the config file — such as GIT_REMOTE_BASE, WORKDIR, and POLL_INTERVAL_MS — are preserved.

​
Upgrading from a pre-0.26 CLI

Before 0.26.0 a host was called a “worker”, and these three settings were named GENTIC_WORKER_ID, GENTIC_WORKER_CREDENTIAL, and GENTIC_WORKER_SETUP_STATE. The CLI still reads the old names from both the config file and the environment, so an existing host does not need to be re-enrolled — upgrade the CLI and it keeps its identity. The config file is rewritten under the new names the next time anything changes it.
The 0.26.0 rename did change the agent API itself, so the CLI and the Gentic app must move together. A CLI older than 0.26.0 is reported as Unsupported in Settings → Workspace → Hosts and is refused new work. Upgrade the CLI on each host — see Installation.

​
Environment variables (alternative)

Environment variables give you fine-grained control over every configuration value and are an alternative to the persisted config file — useful for local development, containers, or CI systems where you manage secrets through the environment directly. Create a .env file in the directory where you run gentic and fill in the values for your environment:
The full list of supported variables is below.

​
Required

​
string
required
The Gentic API endpoint. Use https://app.gentic.chat/api/v1 for the hosted service, or http://localhost:3000/api/v1 when developing against a local web app instance.
​
string
required
The stable host id returned by gentic host connect <code>. Keep it paired with its credential so service and process restarts preserve the same host identity.
​
string
required
A host-specific credential issued by the enrollment exchange. The hosted API verifies the host credential and only returns issues that belong to its user.

​
Optional

​
string
default:"git@github.com:"
The base URL prepended to each project’s owner/repo path when the host clones a repository. With the default value, a project stored as acme/backend is cloned from git@github.com:acme/backend.Change this if your repositories are hosted on GitHub Enterprise, GitLab, or another Git provider:
​
number
default:"1"
The maximum number of issues this host processes at the same time. Each active issue uses its own repository clone and realtime channel. Increase this only when the machine has enough CPU, memory, disk, and agent-provider capacity.
​
string
default:"~/.local/share/gentic/workspaces (Linux)"
The directory where the host creates per-issue repository clones. Each issue gets its own subdirectory. If unset, the host uses an OS-appropriate data directory determined by env-paths:
  • Linux: ~/.local/share/gentic/workspaces
  • macOS: ~/Library/Application Support/gentic/workspaces
Override it to use a custom location, such as a dedicated volume with more disk space:
​
number
default:"3000"
How often (in milliseconds) the host polls the Gentic API for issues with status = 'todo' (or status = 'held' past their usage-limit reset time). The default of 3000 ms (3 seconds) works well for most setups. Increase this value to reduce API traffic on low-priority hosts.

​
Configuration precedence

The host merges all configuration sources in the following order, with later sources winning:
  1. Config file — written by gentic host connect <code> (e.g. ~/.config/gentic/config.json)
  2. .env file — loaded from the working directory at startup
  3. Shell environment variables — exported in the process environment at runtime
This means you can enroll the host once with gentic host connect <code> and use environment variables only for per-deployment overrides like WORKDIR or POLL_INTERVAL_MS. After editing the config file, apply runtime settings without interrupting active issues:
Changes to MAX_CONCURRENT_ISSUES, POLL_INTERVAL_MS, WORKDIR, GIT_REMOTE_BASE, and setup state apply to subsequent host activity. If the new concurrency limit is below the number of issues already running, those issues continue and the host waits before claiming more. Host identity, credential, and API URL changes require gentic restart because they belong to the existing API connection.