opencode-haiilo-ai

Official Haiilo AI plugin for OpenCode — provides authentication (Manual API Key + Okta Device Flow) and automatic model discovery from the Haiilo AI Gateway.

Envoy Gateway validates JWTs statelessly — no login or redirect flow at the gateway.

Architecture

OpenCode (local)
   |
   v
Plugin loader() — attaches Bearer token (JWT) or x-api-key (static key)
   |
   v
GCP Load Balancer — routes to correct backend based on auth header
   |
   +-- x-api-key: sk-*         --> Envoy token-auth gateway (static key validation)
   +-- Authorization: Bearer * --> Envoy jwt-auth gateway (JWT validation via Okta JWKS)
   |
   v
Upstream AI inference services

Employee Setup (step by step)

Prerequisites

• Node.js >= 18
• OpenCode installed
• An Okta account with access to the Haiilo AI authorization server (ask IT)

1 — Install the plugin

Add the plugin to your OpenCode config at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@haiilo/opencode-haiilo-ai"]
}

Restart OpenCode — the plugin is installed automatically via Bun.

2 — Configure OpenCode

Add the haiiloAi provider to your global OpenCode config at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haiiloAi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haiilo AI (gke)",
      "options": {
        "baseURL": "https://ai.haiilo.cloud/v1"
      }
    }
  }
}

3 — Authenticate

1. Open OpenCode
2. Press Ctrl+P → type Connect provider → select it
3. Search for Haiilo AI and select it
4. Select Okta Device Flow
5. A browser window opens automatically — approve the request in your Okta account
6. Models are discovered automatically and injected into the provider

Token is stored at ~/.config/opencode-auth/tokens.json (owner-only permissions).

4 — Use the provider

Press Ctrl+P → Change model → select a model under Haiilo AI (gke).

Requests will include Authorization: Bearer <token> automatically and tokens are refreshed in the background before expiry.

Okta Configuration

The plugin ships with Haiilo's production Okta values — no environment variables needed.

To override (e.g. for local development or a different tenant):

| Variable | Description | |---|---| | OKTA_ISSUER | Okta authorization server URL | | OKTA_CLIENT_ID | OAuth2 client ID | | OKTA_AUDIENCE | API audience identifier | | OKTA_SCOPES | Space-separated scopes (default: openid profile email offline_access haiiloai:inference) | | HAIILO_AI_BASE_URL | Gateway base URL (default: https://ai.haiilo.cloud/v1) |

Token Lifecycle

• Tokens are cached at ~/.config/opencode-auth/tokens.json with 600 permissions (owner only)
• The plugin checks token validity before every startup (config hook) and before every request (auth loader)
• Tokens are automatically refreshed ~5 minutes before expiry using the refresh token
• If refresh fails you will be prompted to re-authenticate via the provider connect screen

Debug logs

tail -f ~/.config/opencode-auth/log/okta-auth.log

Envoy Gateway Configuration

See envoy/jwt-authn.yaml for two ready-to-use config examples:

• Option A — Envoy Gateway SecurityPolicy CRD (recommended for Kubernetes)
• Option B — Raw Envoy http_filters config (for non-Kubernetes deployments)

Project Structure

opencode-haiilo-ai/
├── src/
│   ├── index.ts           # Plugin entry point — auth hook, loader, Device Flow method, model discovery
│   ├── device-flow.ts     # Okta Device Authorization Flow (RFC 8628)
│   ├── token-store.ts     # Filesystem token storage + debug logging
│   └── model-settings.json  # Bundled model metadata overrides
├── envoy/
│   └── jwt-authn.yaml     # Envoy JWT validation config examples
├── dist/                  # Compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

Publishing

To publish a new version to npm:

npm login                    # if not already logged in
npm run build                # produces dist/ (includes bundle.js)
npm publish --access public  # uploads @haiilo/opencode-haiilo-ai to npm

This publishes the TypeScript source. npm runs prepublishOnly automatically, which builds both tsc and esbuild outputs. Consumers install from source and build locally.

Local Development

To test changes without publishing to npm, the plugin can be loaded directly from the filesystem via OpenCode's drop-in plugin directory (~/.config/opencode/plugins/).

Start dev mode

npm run dev

This will:

1. Back up ~/.config/opencode/opencode.json to a timestamped opencode.json.bak-pre-dev-<timestamp> file
2. Remove the @haiilo/opencode-haiilo-ai entry from the plugin array so the cached npm version is not also loaded
3. Build and deploy the plugin to ~/.config/opencode/plugins/haiilo-ai-dev.js

Restart OpenCode — it will load haiilo-ai-dev.js automatically from the drop-in directory.

To iterate on changes:

npm run build:dev   # rebuild and redeploy haiilo-ai-dev.js
# restart OpenCode to pick up the new build

Tip: For continuous rebuilds on every file save, run esbuild in watch mode in a separate terminal:

npx esbuild src/index.ts --bundle --platform=node --format=esm \
  --loader:.json=json --outfile=~/.config/opencode/plugins/haiilo-ai-dev.js --watch

Restart OpenCode after each save to pick up the updated plugin.

Stop dev mode

npm run dev:stop

This will:

1. Remove ~/.config/opencode/plugins/haiilo-ai-dev.js
2. Restore the original @haiilo/opencode-haiilo-ai entry (including its version pin) from the most recent bak-pre-dev-* backup

Restart OpenCode to switch back to the published npm version.

How it works

OpenCode automatically loads any .js or .ts file placed in ~/.config/opencode/plugins/ — no config entry needed.

When @haiilo/opencode-haiilo-ai is absent from the plugin array in opencode.json, the cached npm version at ~/.cache/opencode/packages/@haiilo/ is not loaded. The cache is only read when the package is explicitly listed in the config. The two versions will never double-load.

Security

• No client secret — Device Flow is a public client flow by design (RFC 8628)
• The Okta client ID and issuer URL are not secrets — they are public OAuth2 metadata by design, equivalent to a public OIDC discovery document
• Tokens stored with 0o600 permissions (owner read/write only)
• Refresh tokens minimise re-authentication frequency
• All Okta communication is over HTTPS
• Envoy performs stateless JWT validation only (no session state at the gateway)

License

MIT