starport

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
./starport --version

Quick start

Starport checks every provider in the active Starmap catalog. It registers each provider whose transport and authentication primitive it supports. It separately discovers deployment-owned inference credentials from the ordered profiles in that catalog. You do not select a provider with starport init or a provider-specific flag.

Terminal 1: start Starport

Set one conventional provider credential. This example uses OpenAI:

export OPENAI_API_KEY="replace-with-provider-inference-key"
starport dev

The command starts an isolated gateway at http://127.0.0.1:8080. It uses in-memory state, creates no configuration files, and prints one temporary Starport gateway API key:

Starport development gateway
URL: http://127.0.0.1:8080
Gateway API key (shown once): replace-with-generated-gateway-key

Keep this terminal open.

Terminal 2: call Starport

Copy the printed gateway key into a second terminal. This key authenticates the client to Starport. It is not the provider inference key.

export STARPORT_API_KEY="replace-with-generated-gateway-key"

Readiness is independent of provider credentials. A ready response means that the gateway can accept requests. The authenticated model response contains the current Starmap catalog view.

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

The first provider request proves whether the provider accepts the resolved credential and whether the account can use the selected offering. Starport records authentication, permission, quota, billing, rate-limit, and service failures in its scoped provider state.

For persistent local or production state, run starport init once. The command creates a Starport master key and initial gateway identity. It does not select a provider or persist provider inference credentials. Then use starport serve. See the operator guide.

Local Ollama inference needs no credential. Add each installed model to a reviewed Starmap workspace, and set STARPORT_CATALOG_WORKSPACE_PATH before startup.

Replace an existing gateway URL

Use a Starport gateway key for client authentication.

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.

Provider IDs, credential fields, conventional environment names, defaults, authentication profiles, and endpoints come from the active Starmap catalog. For example, Starport checks OPENAI_API_KEY before STARPORT_OPENAI_API_KEY. A provider that uses an already compiled transport and authentication primitive needs no Starport provider switch.

Starport resolves all catalog providers at startup and, by default, reconciles them every minute. Set STARPORT_CREDENTIAL_SOURCES_RECONCILE_INTERVAL to change that interval. An administrator can also trigger the same shared work:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $STARPORT_API_KEY" \
  http://127.0.0.1:8080/api/v1/admin/providers/refresh

Another process cannot change Starport's process environment. Restart Starport after you change an environment value. File and remote secret sources can return new material during interval or manual reconciliation.

Add _REFERENCE to the catalog-derived Starport name to select a direct secret source. Starport supports Google Cloud Secret Manager, Azure Key Vault, AWS Secrets Manager, HashiCorp Vault KV v2, and OpenBao KV v2. For example:

export STARPORT_OPENAI_API_KEY_REFERENCE='aws-secrets-manager:starport/openai#api-key'

The operator guide defines the resource syntax, source authentication, version selection, and fallback rule.

To consume verified catalog publications from a Starmap server, set its versioned API base URL:

export STARPORT_CATALOG_REMOTE_URL="https://catalog.example.com/api/v1"
export STARPORT_CATALOG_REMOTE_API_KEY="replace-if-the-server-requires-one"

Remote mode keeps the last accepted generation for restart and recovery. It is mutually exclusive with a local catalog workspace and local acquisition. See the remote catalog guide.

See the configuration reference and operator guide for production settings.

Cloud credentials

Vertex AI and Azure OpenAI can use renewable default cloud credentials. Their project, location, and endpoint fields use the conventional names declared by Starmap:

export GOOGLE_CLOUD_PROJECT="replace-with-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

export AZURE_OPENAI_ENDPOINT="https://replace-with-resource.openai.azure.com"

Vertex AI uses Google Application Default Credentials. Azure OpenAI uses AZURE_OPENAI_API_KEY when present. Without it, Azure OpenAI uses DefaultAzureCredential. Starport gets renewable bearer tokens before an inference request uses them.

Starmap catalog-acquisition credentials remain separate from Starport inference credentials.

Containers

Pull a versioned image and verify its GitHub attestation:

STARPORT_VERSION="$(gh release view \
  --repo agentstation/starport \
  --json tagName \
  --jq '.tagName | ltrimstr("v")')"
docker pull "ghcr.io/agentstation/starport:$STARPORT_VERSION"
gh attestation verify "oci://ghcr.io/agentstation/starport:$STARPORT_VERSION" \
  --repo agentstation/starport \
  --signer-workflow agentstation/starport/.github/workflows/release.yaml
docker run --rm "ghcr.io/agentstation/starport:$STARPORT_VERSION" --version

The Compose file builds Starport locally and uses Valkey for shared state. Put the master key and any catalog-declared provider values in the ignored .env file. This example uses OpenAI:

cp .env.example .env
# Edit .env. Set STARPORT_SECURITY_MASTER_KEY and OPENAI_API_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.
• Catalog-driven providers over the compiled OpenAI, Anthropic, Google Cloud, Google AI Studio, and Ollama transport primitives.
• Encrypted provider credentials, renewable cloud credentials, and direct secret-source references.
• 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

• Architecture
• Operator guide
• Vertex AI configuration
• Model catalog contract
• Documentation index

License and security

Starport uses the GNU AGPLv3 license. See LICENSE.

Report vulnerabilities through the process in SECURITY.md.