Skip to content
This repository was archived by the owner on Oct 16, 2026. It is now read-only.

Getting Started

Jump to bottom
LazyGreed edited this page Sep 20, 2026 · 2 revisions

Getting Started

Requirements

For the normal release installation:

  • Linux x86_64 or aarch64
  • a shell
  • curl

The installer downloads a prebuilt binary for supported Linux architectures, so Rust and Node.js are not required for a normal release installation.

Building from source additionally requires:

  • Rust / Cargo
  • Git
  • Node.js
  • npm

Other platforms may work from source but are not currently targeted by the release installer.

Install

The recommended installation needs no .env file and no hand-written configuration file.

curl -fsSL https://raw.githubusercontent.com/LazyGreed/kinetix/main/install.sh | bash

By default, the installer:

  1. Resolves the latest GitHub release.
  2. Downloads the matching prebuilt binary for x86_64 or aarch64.
  3. Verifies the release SHA-256 checksum when the checksum manifest is available.
  4. Falls back to a source build if a usable prebuilt release cannot be obtained.
  5. Installs kinetix under ~/.local/bin.
  6. Adds the binary directory to your shell PATH when necessary.
  7. Runs kinetix init.
  8. Creates the configuration, data, and state directories.
  9. Generates and prints the dashboard admin password once.

Kinetix stores its default state under:

~/.config/kinetix
~/.local/share/kinetix
~/.local/state/kinetix

Pin a release

Set KINETIX_VERSION to a release tag:

curl -fsSL https://raw.githubusercontent.com/LazyGreed/kinetix/main/install.sh \
  | KINETIX_VERSION=v0.1.0 bash

Install from main

To explicitly build the current development branch:

curl -fsSL https://raw.githubusercontent.com/LazyGreed/kinetix/main/install.sh \
  | KINETIX_VERSION=main bash

A source build requires Rust/Cargo, Git, Node.js, and npm.

Custom install prefix

The default install prefix is:

~/.local

Override it with:

curl -fsSL https://raw.githubusercontent.com/LazyGreed/kinetix/main/install.sh \
  | KINETIX_PREFIX=/custom/prefix bash

First configuration

Kinetix intentionally ships without provider presets. Add the upstreams, models, credentials, and prices appropriate for your deployment.

The following example configures Gemini.

1. Add a provider and account

kinetix provider add \
  --name Gemini \
  --base-url https://generativelanguage.googleapis.com/v1beta \
  --wire-format gemini \
  --auth-scheme custom_header \
  --custom-header-name x-goog-api-key \
  --api-key "$GEMINI_API_KEY" \
  --account-label primary

Passing both --api-key and --account-label creates the provider's first credential account at the same time.

2. Register a model

kinetix model add \
  --provider Gemini \
  --upstream-id gemini-2.5-flash \
  --display-name "Gemini 2.5 Flash"

Optional model metadata includes context limits, capabilities, and pricing.

See Providers for the full provider and model configuration model.

3. Create a virtual key

kinetix key create --name local-client --owner me

The resulting secret begins with:

sk-kinetix-...

The plaintext secret is shown once. Kinetix stores only its hash.

4. Start the proxy

kinetix serve

The default local address is:

http://127.0.0.1:8080

The embedded dashboard is available at:

http://127.0.0.1:8080/admin

Log in with the admin password printed during installation or kinetix init.

Verify the installation

Health check

curl -s http://127.0.0.1:8080/healthz

A healthy instance returns a response similar to:

{
  "status": "ok",
  "uptime_secs": 3,
  "database": "ok",
  "data_plane": "serving",
  "control_plane": "ok"
}

status: ok indicates that the data plane can serve requests.

A degraded control plane does not necessarily make the inference data plane unavailable: Kinetix can continue serving from its in-memory registry snapshot in supported failure scenarios. See Observability for health semantics.

Send an inference request

Using the virtual key created earlier:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-kinetix-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Kinetix."
      }
    ]
  }'

A successful response confirms the complete path:

client
  → virtual-key authentication
  → model resolution
  → provider account
  → upstream model
  → translated response

Point a client at Kinetix

Kinetix supports OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages clients.

OpenAI-compatible clients

Use:

http://127.0.0.1:8080/v1

with a Kinetix virtual key.

Example Pi configuration:

{
  "providers": {
    "kinetix": {
      "baseUrl": "http://127.0.0.1:8080/v1",
      "apiKey": "sk-kinetix-...",
      "api": "openai-completions"
    }
  }
}

Anthropic-format clients

Point Anthropic-format clients at:

http://127.0.0.1:8080

Kinetix serves:

POST /v1/messages

OpenAI Responses clients

Modern coding agents that use the Responses API can use:

POST /v1/responses

See Compatibility for protocol behavior and documented deviations.

See Pi Compatibility for Pi-specific setup and acceptance notes.

Useful commands

Inspect the installation:

kinetix status

Run diagnostics:

kinetix doctor

Show the command surface:

kinetix --help

Examples:

kinetix provider --help
kinetix model --help
kinetix account --help
kinetix route --help
kinetix alias --help
kinetix key --help

The Kinetix binary is both the inference server and the administrative CLI. Administrative commands operate directly on the SQLite control plane and generally work while the server is stopped.

See CLI Reference for the complete command surface.

Docker

For Docker deployment:

cp .env.docker.example .env
docker compose up -d --build
docker compose logs kinetix | grep -i password

All persistent state is stored under the container's /data volume.

See Docker for the full container workflow.

Production deployment

The default service binds locally. For production, keep Kinetix behind an appropriate authenticated reverse proxy or tunnel rather than exposing the administrative surface directly.

The repository includes:

  • a hardened systemd unit
  • graceful shutdown/drain behavior
  • automatic restart
  • Cloudflare Tunnel guidance
  • Cloudflare Access guidance
  • backup/restore procedures
  • upgrade procedures

See Deployment and deploy/README.md.

Uninstall

Using the installed binary:

kinetix uninstall

Additional options:

kinetix uninstall [--yes] [--remove-binary] [--keep-data] [--dry-run]

Or use the standalone uninstall script:

curl -fsSL https://raw.githubusercontent.com/LazyGreed/kinetix/main/uninstall.sh | bash

Next steps

Clone this wiki locally