Metadata-Version: 2.4
Name: ghostai-connect
Version: 0.2.2
Summary: GhostAI BYO-inference connector — outbound WSS tunnel from a customer-run Ollama/vLLM to ghostai-relay, no inbound firewall rule required
Author: Dymium, Inc.
License-Expression: LicenseRef-Proprietary
Keywords: ghostai,byo-inference,connector,relay
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.26
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic>=2.5.3
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Dynamic: license-file

# GhostAI Connect

GhostAI Connect links an inference server you run yourself (Ollama, vLLM, or
any OpenAI-compatible server) to GhostAI. It opens one outbound WebSocket
connection to the GhostAI relay, so you never open an inbound firewall port.

## Install

Python 3.10 or later:

```bash
pipx install ghostai-connect      # or: pip install ghostai-connect
ghostai-connect --version
```

Or use the container image for `linux/amd64` and `linux/arm64`:
`ghcr.io/dymium-io/ghostai-connect:<version>`.

## Verify before you run it

The container image is signed keyless with Sigstore by this repository's
release workflow. With [`cosign`](https://docs.sigstore.dev/cosign/system_config/installation/)
v2 or later:

```bash
cosign verify \
  --certificate-identity-regexp '^https://github\.com/dymium-io/ghostai-connect/\.github/workflows/publish-image\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/dymium-io/ghostai-connect:<version>
```

The PyPI files carry [PEP 740](https://peps.python.org/pep-0740/) attestations
from the same repository. With `pipx install pypi-attestations`:

```bash
pypi-attestations verify pypi \
  --repository https://github.com/dymium-io/ghostai-connect \
  pypi:ghostai_connect-<version>-py3-none-any.whl
```

RELEASE_SIGNING.md in the source repository has the details.

## Enroll and run

Use the enrollment command shown in the GhostAI admin console. The token is
single-use.

```bash
ghostai-connect enroll <token> \
  --base-url https://your-ghostai-instance.example.com \
  --relay-url wss://relay-connector.your-ghostai-instance.example.com/connector/ws

ghostai-connect run      # runs until stopped; reconnects automatically
ghostai-connect doctor   # last heartbeat, registration status, last error
```

The enrolled credential is stored in `~/.config/ghostai-connect/config.json`
with mode `0600`.

| Environment variable | Meaning | Default |
|---|---|---|
| `GHOSTAI_CONNECT_LOCAL_URL` | Your local inference server | `http://localhost:11434` |
| `GHOSTAI_CONNECT_MAX_CONCURRENCY` | Concurrent requests forwarded to it | `4` |
| `GHOSTAI_CONNECT_MAX_RECONNECT_ATTEMPTS` | Give up after this many consecutive failed reconnects | retry forever |

### In a container

The image runs `ghostai-connect run`. Enroll once into a volume, then mount
that volume when you start the connector:

```bash
docker run --rm -v ghostai-connect:/home/connect/.config/ghostai-connect \
  ghcr.io/dymium-io/ghostai-connect:<version> \
  enroll <token> --base-url ... --relay-url ...

docker run -d --name ghostai-connect \
  -v ghostai-connect:/home/connect/.config/ghostai-connect \
  -e GHOSTAI_CONNECT_LOCAL_URL=http://ollama:11434 \
  ghcr.io/dymium-io/ghostai-connect:<version>
```

## Upgrade

```bash
pipx upgrade ghostai-connect      # or: pip install --upgrade ghostai-connect
```

Your enrollment is kept. Restart `ghostai-connect run` after upgrading.

## License

Proprietary. Copyright (c) 2026 Dymium, Inc. All rights reserved. Use requires
an active GhostAI subscription, under your agreement with Dymium, Inc.; see the
LICENSE file included with the package. Questions: support@dymium.io.
