README
¶
Starport
Starport is a self-hosted LLM inference gateway. It serves OpenAI-compatible
APIs at /v1 and OpenRouter-compatible APIs at /api/v1.
Starport uses Starmap as its only source of provider, model, capability, context, price, and service facts. Starport owns inference credentials, gateway identities, routing policy, execution, and HTTP protocols.
Install
Install the released cask on macOS or Linux:
brew install agentstation/tap/starport
starport --version
The current public release also contains checksummed archives for macOS, Linux, and Windows. Download an archive from GitHub Releases.
To build from source, install the Go version from go.mod, then run:
git clone https://github.com/agentstation/starport.git
cd starport
make build
export STARPORT_BIN="$PWD/starport"
"$STARPORT_BIN" --version
Quick start
Set the executable once. The default uses a release installation from
PATH. Source builders keep the value from the preceding build commands.
export STARPORT_BIN="${STARPORT_BIN:-starport}"
You need an OpenAI inference key. Initialize one local Starport instance:
export STARPORT_PROVIDERS_OPENAI_API_KEY="replace-with-provider-inference-key"
"$STARPORT_BIN" init --provider openai
Initialization creates a provider-credential master key and one gateway identity. It writes the OpenAI key, master key, and local state under the owner-only platform configuration directory. It prints the new gateway API key once. Save that key, then set it for the client examples:
export STARPORT_API_KEY="replace-with-gateway-api-key-from-init"
Inspect the effective paths and startup state:
"$STARPORT_BIN" config paths
"$STARPORT_BIN" config validate
"$STARPORT_BIN" doctor --probe
Start the gateway in this terminal. Use another terminal for the requests:
"$STARPORT_BIN" serve
Check readiness and the authenticated model catalog:
curl --fail http://127.0.0.1:8080/health/ready
curl --fail-with-body \
-H "Authorization: Bearer $STARPORT_API_KEY" \
http://127.0.0.1:8080/api/v1/models
Send an OpenRouter-style chat 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://127.0.0.1:8080/api/v1/chat/completions
For local Ollama inference, run starport init --provider ollama. Add each
installed model to a reviewed Starmap workspace before startup. Then set
STARPORT_CATALOG_WORKSPACE_PATH to that workspace.
Replace an existing gateway URL
Use a Starport gateway key for client authentication.
| Client contract | Base URL |
|---|---|
| OpenAI | http://127.0.0.1:8080/v1 |
| OpenRouter | http://127.0.0.1:8080/api/v1 |
OpenAI Python example:
import os
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8080/v1",
api_key=os.environ["STARPORT_API_KEY"],
)
response = client.chat.completions.create(
model="openai/gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
)
For an OpenRouter client, replace its default base URL with
http://127.0.0.1:8080/api/v1. Keep the client request and response types.
Configuration
Starport reads config.env from the platform user configuration directory.
Process environment variables override the file. starport config paths
prints the resolved paths.
Set STARPORT_CONFIG_DIR to an absolute path for an isolated development or
CI instance. This value changes the configuration, data, and rate-limit paths
together.
starport config show prints the effective schema and hides secret values.
starport doctor runs passive checks. Add --probe for read-only storage and
identity checks.
See the configuration reference and operator guide for production settings.
Cloud credentials
Vertex AI and Azure OpenAI accept static credentials or renewable default
cloud credentials. Both adapters require an explicit AUTH_MODE.
export STARPORT_PROVIDERS_GOOGLE_VERTEX_AUTH_MODE=default
export STARPORT_PROVIDERS_GOOGLE_VERTEX_PROJECT_ID="replace-with-project-id"
export STARPORT_PROVIDERS_GOOGLE_VERTEX_LOCATION="us-central1"
export STARPORT_PROVIDERS_AZURE_OPENAI_AUTH_MODE=default
export STARPORT_PROVIDERS_AZURE_OPENAI_BASE_URL="https://replace-with-resource.openai.azure.com"
Default mode uses Google Application Default Credentials or Azure
DefaultAzureCredential. Static mode uses the provider API_KEY variable.
Starport rejects a static key in default mode.
Starmap catalog-acquisition credentials remain separate from Starport inference credentials.
Containers
Pull a versioned image and verify its GitHub attestation:
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 uses Valkey for shared state:
export STARPORT_SECURITY_MASTER_KEY="replace-with-random-secret-at-least-32-bytes"
export STARPORT_PROVIDERS_OPENAI_API_KEY="replace-with-provider-inference-key"
docker compose up --build -d valkey
docker compose run --rm starport init --configured-storage --name primary-admin
docker compose up -d starport
Save the gateway key from initialization. Do not initialize the same identity repository again.
Version 1 scope
Version 1 includes:
- Chat completions, streaming chat, embeddings, and model discovery.
- Exact provider and model routing with fallback and
openrouter/auto. - OpenAI, Anthropic, Google AI Studio, Vertex AI, Groq, Mistral, Azure OpenAI, and Ollama adapters.
- Encrypted provider credentials and renewable cloud credentials.
- Header-only gateway authentication and per-key rate limits.
- Tenant-safe response caching.
- Badger storage for one process and Valkey storage for multiple processes.
Starport uses direct changes and has no legacy provider aliases or storage readers. It does not yet promise a compatibility window.
Develop
make deps
make check
bash scripts/smoke-first-run.sh
bash scripts/smoke-openrouter-sdks.sh
make check reads files but does not change them. Use make format or
make tidy when you want to change source or module files.
See the development guide and contribution guide.
Documentation
License and security
Starport uses the GNU AGPLv3 license. See LICENSE.
Report vulnerabilities through the process in SECURITY.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
starport
command
Package main is the Starport process boundary.
|
Package main is the Starport process boundary. |
|
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. |
|
cli
Package cli owns Starport command contracts and process-independent execution.
|
Package cli owns Starport command contracts and process-independent execution. |
|
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. |
|
diagnosis
Package diagnosis owns read-only startup checks for Starport.
|
Package diagnosis owns read-only startup checks for Starport. |
|
doclinks
Package doclinks verifies local destinations in Markdown documents.
|
Package doclinks verifies local destinations in Markdown documents. |
|
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. |
|
providerauth
Package providerauth owns renewable credentials for provider inference.
|
Package providerauth owns renewable credentials for provider inference. |
|
providers
Package providers owns the projection from operator inference settings to compiled adapter configuration.
|
Package providers owns the projection from operator inference settings to compiled adapter configuration. |
|
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. |
|
setup
Package setup owns safe first-run initialization for a local Starport instance.
|
Package setup owns safe first-run initialization for a local Starport instance. |
|
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
|
|
|
doclinks
command
|
|
|
sdk-smoke-server
command
Command sdk-smoke-server serves deterministic OpenRouter protocol fixtures.
|
Command sdk-smoke-server serves deterministic OpenRouter protocol fixtures. |