nexus-claude-api/docs/PACKAGING_DISTRIBUTION.md

Python Internal Distribution Guide

This document describes how to distribute nexus-claude-api internally without publishing to PyPI.

Recommended Options

Use one of these two approaches:

• Wheel distribution: build a .whl file and send it to colleagues. This is best for stable internal releases.
• Private Git installation: let colleagues install directly from the company Git repository. This is best for teammates who can access the source code or need frequent updates.

Both options require:

• Python >=3.11
• Access to PyPI or the company Python package mirror for runtime dependencies
• A personal AI Nexus API key

Do not share nexus-claude-api.local.json, .env, logs, or any personal API key.

Option 1: Build and Share a Wheel

A wheel is the standard Python install package format. It is not an .exe; colleagues install it with pip, then run the installed nexus-claude-api command.

Publisher Steps

1. Confirm the package version in pyproject.toml:

   [project]
   name = "nexus-claude-api"
   version = "0.1.0"
   

   Update the version for every released package. Avoid sending different builds with the same version.

2. Run the supported checks:

   uv sync --extra dev
   uv run pytest
   uv run nexus-claude-api start --dry-run
   

3. Build the package:

   uv build
   

   This creates files under dist/, usually:

   dist/nexus_claude_api-0.1.0-py3-none-any.whl
   dist/nexus_claude_api-0.1.0.tar.gz
   

4. Test the wheel in a clean environment:

   py -3.11 -m venv C:\Temp\nexus-claude-api-test
   C:\Temp\nexus-claude-api-test\Scripts\python.exe -m pip install .\dist\nexus_claude_api-0.1.0-py3-none-any.whl
   C:\Temp\nexus-claude-api-test\Scripts\nexus-claude-api.exe start --dry-run
   

5. Send only the .whl file to colleagues through an approved internal channel.

Colleague Installation

Install the wheel:

py -3.11 -m pip install .\nexus_claude_api-0.1.0-py3-none-any.whl

Configure the personal Nexus key:

nexus-claude-api config set --api-key "your-nexus-api-key"

Start the local proxy and print the Claude Code helper:

nexus-claude-api start --port 4141 --claude-code

If PowerShell cannot find the installed script, use the module form:

py -3.11 -m nexus_claude_api start --port 4141 --claude-code

Upgrade

Send a new wheel with a new version, then ask colleagues to run:

py -3.11 -m pip install --upgrade .\nexus_claude_api-0.1.1-py3-none-any.whl

Option 2: Install from Private Git

Private Git installation avoids manual wheel sharing. It still uses the Python package metadata from pyproject.toml, so the installed command is the same.

Publisher Steps

1. Push the code to the company Git repository.

2. Update the version in pyproject.toml for each released version.

3. Tag stable versions:

   git tag v0.1.0
   git push origin v0.1.0
   

   For the next release:

   git tag v0.1.1
   git push origin v0.1.1
   

4. Share an install command that points to a tag:

   py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"
   

Prefer tags or exact commit SHAs. Avoid asking normal users to install from main, because repeated installs can produce different code over time.

Colleague Installation

Install from the company Git repository:

py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"

Configure the personal Nexus key:

nexus-claude-api config set --api-key "your-nexus-api-key"

Start the local proxy:

nexus-claude-api start --port 4141 --claude-code

Upgrade

Upgrade to a newer tag:

py -3.11 -m pip install --upgrade "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.1"

Development Clone

For colleagues who will modify or test the source code:

git clone https://company-git.example.com/group/nexus-claude-api.git
cd nexus-claude-api
uv sync --extra dev
uv run nexus-claude-api start --dry-run

Choosing Between the Two

• Use wheel distribution for normal internal users who only need a stable tool.
• Use private Git installation for colleagues who understand the repository, need fast updates, or help develop the project.
• Keep version numbers and Git tags aligned. For example, pyproject.toml version 0.1.0 should correspond to tag v0.1.0.

Release Checklist

Before sharing a release:

• Run uv run pytest.
• Run uv run nexus-claude-api start --dry-run.
• Test wheel installation in a clean Python environment.
• If using Git installation, test install from the exact tag.
• Confirm no personal credentials are included.
• Confirm nexus-claude-api.local.json, .env, logs, caches, and dist/ artifacts are not committed accidentally.