README
¶
Starport
Starport is a self-hosted LLM gateway written in Go. It exposes OpenAI and OpenRouter HTTP contracts over one provider-neutral inference core. It uses Starmap as the only source of model, provider, capability, context, and price facts.
Status: v1. Starport uses direct breaking changes. Starport does not yet publish a compatibility policy. It has no legacy provider aliases, storage prefixes, or schema readers.
Version 1 Scope
The current version includes:
- OpenAI-compatible APIs under
/v1. - OpenRouter-compatible APIs under
/api/v1. - Chat completions, streaming chat, embeddings, and model discovery.
- Exact model and provider routing with fallback and
openrouter/auto. - One total attempt budget and offering-level availability state.
- OpenAI, Anthropic, Google AI Studio, Vertex AI, Groq, Mistral, Azure OpenAI, and Ollama adapters.
- Encrypted BYOK provider credentials.
- Header-only gateway authentication and per-key rate limits.
- Tenant-safe response caching.
- Badger storage for one node and Valkey storage for multiple nodes.
- One binary with explicit startup and shutdown ownership.
Content moderation, preset APIs, OpenTelemetry, complete billing analytics, webhooks, and enterprise SSO/RBAC are outside the current v1 scope.
First Start
Requirements:
- A Starport v1 binary, container image, or Go 1.26.5 source toolchain.
- One configured inference provider.
- Two different secrets with at least 32 characters each.
Install a verified archive from the GitHub release:
gh release download v1.0.0 \
--repo agentstation/starport \
--pattern 'starport_1.0.0_linux_x86_64.tar.gz' \
--pattern 'checksums.txt'
sha256sum --check --ignore-missing checksums.txt
gh attestation verify starport_1.0.0_linux_x86_64.tar.gz \
--repo agentstation/starport \
--signer-workflow agentstation/starport/.github/workflows/release.yaml
tar -xzf starport_1.0.0_linux_x86_64.tar.gz
./starport --version
The release also contains Linux and macOS archives and Windows zip files for amd64 and arm64. You can build the exact tag from source:
go install github.com/agentstation/starport/cmd/starport@v1.0.0
Copy the example configuration:
cp .env.example .env
Set the provider-credential master key, the first gateway key, and one provider key:
STARPORT_SECURITY_MASTER_KEY=<random master secret>
STARPORT_SECURITY_BOOTSTRAP_API_KEY=<different random gateway key>
STARPORT_PROVIDERS_OPENAI_API_KEY=<provider inference key>
Build and start Starport:
make build
./starport serve
If identity storage is empty, Starport requires a bootstrap key. See the operator guide for the first administrator-key rotation procedure.
Check health:
curl --fail http://localhost:8080/health/live
curl --fail http://localhost:8080/health/ready
Client Configuration
Use a Starport gateway API key for client authentication.
| Contract | Base URL |
|---|---|
| OpenAI | http://localhost:8080/v1 |
| OpenRouter | http://localhost:8080/api/v1 |
OpenAI SDK example:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="<starport-gateway-key>",
)
response = client.chat.completions.create(
model="openai/gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
)
OpenRouter-style request:
curl --fail-with-body \
-H "Authorization: Bearer $STARPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openrouter/auto","messages":[{"role":"user","content":"Hello"}]}' \
http://localhost:8080/api/v1/chat/completions
Catalog Identities
Starmap is the source of provider IDs, model IDs, offerings, capabilities,
prices, and provider service metadata. Read the active values from
GET /api/v1/providers and GET /api/v1/models. Starport keeps each ID exact
and opaque. It does not normalize old or alternate names.
Containers
Pull the signed-release identity by version, not by an unverified digest:
docker pull ghcr.io/agentstation/starport:1.0.0
gh attestation verify oci://ghcr.io/agentstation/starport:1.0.0 \
--repo agentstation/starport \
--signer-workflow agentstation/starport/.github/workflows/release.yaml
docker run --rm ghcr.io/agentstation/starport:1.0.0 --version
The Compose file builds Starport locally and starts it with Valkey:
export STARPORT_SECURITY_MASTER_KEY=<master-secret>
export STARPORT_SECURITY_BOOTSTRAP_API_KEY=<bootstrap-key>
export STARPORT_PROVIDERS_OPENAI_API_KEY=<provider-inference-key>
docker compose up --build
For a single-node container, mount /var/lib/starport/data and pass the
required secrets through an environment file or secret manager.
Development and Verification
go test ./...
bash scripts/verify-starmap-ownership.sh
bash scripts/verify-v1-architecture.sh
bash scripts/verify-v1-release.sh
make lint
make build
bash scripts/smoke-openrouter-sdks.sh
The smoke runner tests raw HTTP plus the pinned official OpenRouter Python, TypeScript, and Go SDKs. A missing or incompatible SDK is a failed gate.
Documentation
License and Security
Starport uses the GNU AGPLv3 license. See LICENSE.
Report security vulnerabilities as described in SECURITY.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
starport
command
Package main is the entry point for the Starport application.
|
Package main is the entry point for the Starport application. |
|
Package main demonstrates how to use cache control with Starport
|
Package main demonstrates how to use cache control with Starport |
|
internal
|
|
|
app
Package app owns Starport production composition and lifecycle.
|
Package app owns Starport production composition and lifecycle. |
|
availability
Package availability owns runtime state for exact provider offerings.
|
Package availability owns runtime state for exact provider offerings. |
|
cache
Package cache provides a multi-layer caching system for LLM responses with in-memory and persistent storage backends.
|
Package cache provides a multi-layer caching system for LLM responses with in-memory and persistent storage backends. |
|
catalog
Package catalog owns Starport's immutable view of Starmap facts and the separately versioned runtime availability used to derive routable models.
|
Package catalog owns Starport's immutable view of Starmap facts and the separately versioned runtime availability used to derive routable models. |
|
chatui
Package chatui provides a web-based chat interface for interacting with LLM models through Starport.
|
Package chatui provides a web-based chat interface for interacting with LLM models through Starport. |
|
config
Package config provides configuration management for Starport.
|
Package config provides configuration management for Starport. |
|
credentials
Package credentials owns encrypted provider credentials and their durable repository.
|
Package credentials owns encrypted provider credentials and their durable repository. |
|
execution
Package execution owns attempt state, retry and fallback budgets, and the response-byte commitment boundary for inference execution.
|
Package execution owns attempt state, retry and fallback budgets, and the response-byte commitment boundary for inference execution. |
|
failure
Package failure owns normalized inference failure semantics.
|
Package failure owns normalized inference failure semantics. |
|
httpapi/openai
Package openai adapts the OpenAI HTTP protocol to canonical inference values.
|
Package openai adapts the OpenAI HTTP protocol to canonical inference values. |
|
httpapi/openrouter
Package openrouter adapts the OpenRouter HTTP protocol to canonical inference values.
|
Package openrouter adapts the OpenRouter HTTP protocol to canonical inference values. |
|
httpclient
Package httpclient provides optimized HTTP clients for LLM providers with built-in monitoring and connection pooling.
|
Package httpclient provides optimized HTTP clients for LLM providers with built-in monitoring and connection pooling. |
|
identity
Package identity owns gateway API-key identity and persistence.
|
Package identity owns gateway API-key identity and persistence. |
|
inference
Package inference owns provider-neutral inference values and stream events.
|
Package inference owns provider-neutral inference values and stream events. |
|
presets
Package presets owns reusable inference configuration presets and persistence.
|
Package presets owns reusable inference configuration presets and persistence. |
|
providers/byok
Package byok manages API keys for external LLM providers.
|
Package byok manages API keys for external LLM providers. |
|
providers/connectors
Package connectors provides interfaces and types for LLM provider integrations
|
Package connectors provides interfaces and types for LLM provider integrations |
|
proxy
Package proxy provides a high-performance LLM request proxy with support for multiple providers, intelligent routing, caching, and extensible middleware.
|
Package proxy provides a high-performance LLM request proxy with support for multiple providers, intelligent routing, caching, and extensible middleware. |
|
ratelimit
Package ratelimit owns fixed-window rate-limit state and persistence.
|
Package ratelimit owns fixed-window rate-limit state and persistence. |
|
registry
Package registry manages LLM provider connectors
|
Package registry manages LLM provider connectors |
|
repositorytest
Package repositorytest supplies storage backends for repository contract tests.
|
Package repositorytest supplies storage backends for repository contract tests. |
|
responsecache
Package responsecache owns response-cache eligibility, semantic identity, versioned canonical records, and stream replay.
|
Package responsecache owns response-cache eligibility, semantic identity, versioned canonical records, and stream replay. |
|
router
Package router provides model routing and fallback capabilities for the Starport gateway.
|
Package router provides model routing and fallback capabilities for the Starport gateway. |
|
routing
Package routing plans deterministic provider attempts from immutable inputs.
|
Package routing plans deterministic provider attempts from immutable inputs. |
|
server
Package server provides HTTP server implementation for Starport.
|
Package server provides HTTP server implementation for Starport. |
|
server/controllers
Package controllers contains HTTP handlers for the Starport API.
|
Package controllers contains HTTP handlers for the Starport API. |
|
server/dto
Package dto owns shared administrative HTTP response values.
|
Package dto owns shared administrative HTTP response values. |
|
server/requestctx
Package requestctx defines typed request context values shared by the server middleware and HTTP controllers.
|
Package requestctx defines typed request context values shared by the server middleware and HTTP controllers. |
|
storage
Package storage provides a key-value storage abstraction layer with support for multiple backend implementations including embedded and distributed stores.
|
Package storage provides a key-value storage abstraction layer with support for multiple backend implementations including embedded and distributed stores. |
|
testutil
Package testutil provides common test utilities for the Starport project
|
Package testutil provides common test utilities for the Starport project |
|
scripts
|
|
|
sdk-smoke-server
command
Command sdk-smoke-server serves deterministic OpenRouter protocol fixtures.
|
Command sdk-smoke-server serves deterministic OpenRouter protocol fixtures. |
Click to show internal directories.
Click to hide internal directories.