> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gentic.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Gentic Agent Worker on Your Server

> Deploy the Gentic agent worker using the prebuilt standalone binary or from source with Node.js. Includes Git and credentials setup.

The agent worker ships as a standalone binary compiled with [Bun](https://bun.sh) — 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.

## Option A: Standalone binary (recommended for production)

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.

<Note>
  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.
</Note>

**Supported targets**

| Target             | Platform             |
| ------------------ | -------------------- |
| `bun-linux-x64`    | Linux, x86-64        |
| `bun-linux-arm64`  | Linux, ARM64         |
| `bun-darwin-x64`   | macOS, Intel         |
| `bun-darwin-arm64` | macOS, Apple Silicon |

### Download a prebuilt release

<Steps>
  <Step title="Download the archive for your platform">
    Go to the [GitHub Releases page](https://github.com/kprovorov/gentic/releases) and download `gentic-<target>.tar.gz` for your platform, along with `checksums.txt` to verify the download.

    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Verify the checksum">
    ```bash theme={null}
    sha256sum --check --ignore-missing checksums.txt
    ```
  </Step>

  <Step title="Extract the archive">
    ```bash theme={null}
    tar -xzf gentic-bun-linux-x64.tar.gz
    ```

    You will see the `gentic` binary and the `vendor/` directory alongside it.
  </Step>

  <Step title="Run the worker">
    Set your credentials in the environment and start the worker:

    ```bash theme={null}
    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](/agent/service-management).
  </Step>
</Steps>

<Warning>
  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.
</Warning>

### 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.

<Steps>
  <Step title="Install dependencies from the repository root">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Run the build script">
    Pass the Bun compile target and the output directory as arguments:

    ```bash theme={null}
    cd apps/gentic
    ./scripts/build-binary.sh bun-linux-x64 dist/linux-x64
    ```

    Substitute `bun-linux-x64` with any supported target listed above.
  </Step>

  <Step title="Copy the output directory to your server">
    ```bash theme={null}
    scp -r dist/linux-x64 user@your-server:/opt/gentic
    ```
  </Step>
</Steps>

***

## 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.

<Steps>
  <Step title="Clone or upload the repository to the server">
    ```bash theme={null}
    git clone git@github.com:kprovorov/gentic.git
    cd gentic
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build the agent package">
    ```bash theme={null}
    pnpm --filter @gentic/gentic build
    ```
  </Step>

  <Step title="Start the worker">
    ```bash theme={null}
    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](/agent/service-management).
  </Step>
</Steps>

***

## 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.

<Steps>
  <Step title="Generate a deploy key or use a machine user key">
    ```bash theme={null}
    ssh-keygen -t ed25519 -C "gentic-worker" -f ~/.ssh/gentic_deploy
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure SSH to use the key">
    Add the following to `~/.ssh/config` on the server:

    ```text theme={null}
    Host github.com
      IdentityFile ~/.ssh/gentic_deploy
      IdentitiesOnly yes
    ```
  </Step>
</Steps>

***

## 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

<Steps>
  <Step title="Install the Codex CLI in the worker environment">
    Follow the [Codex installation instructions](https://github.com/openai/codex) for your platform.
  </Step>

  <Step title="Authenticate Codex">
    Run `codex` once interactively to complete authentication before starting the worker.
  </Step>

  <Step title="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:

    ```bash theme={null}
    export CODEX_PATH=/usr/local/bin/codex
    ```
  </Step>
</Steps>

<Tip>
  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.
</Tip>