Local Connector

Vela Local Connector is a CLI that connects an OpenAI-compatible endpoint on a customer device or internal network to Vela without a public inbound endpoint. Vela does not connect directly to the local runtime; the connector retrieves jobs through outbound polling.

Install

npm install -g @vel4ai/local-connector
vela --help

For pre-publish repo development, use:

pnpm --filter @vel4ai/local-connector mock:local-llm
pnpm --filter @vel4ai/local-connector build

Basic Commands

Use the guided setup for first run. It logs in when needed, reads the local /models endpoint, proposes model mappings, and registers the connector.

vela setup --local-base-url http://127.0.0.1:11434/v1
vela start --detach
vela status
vela doctor

Manual setup is still supported.

vela login --email [email protected] --otp 000000
vela add --local-base-url http://127.0.0.1:1234/v1 --model local/mock=mock-local-llm --label "Laptop mock LLM"
vela start

vela start runs in the foreground. vela start --detach starts the same connector in a background child process, prints the PID, and returns to the shell. --background is also accepted. Detached mode is not an OS service manager; use vela status to confirm that Vela sees the connector online.

Every command has command-specific help, for example vela add --help.

Endpoint Requirements

The local endpoint must expose these OpenAI-compatible APIs.

endpoint	Purpose
GET /models	Check available local model IDs
POST /chat/completions	Non-streaming and streaming chat completions

Model Mapping

--model local/mock=mock-local-llm maps the Vela model ID local/mock to the local endpoint model mock-local-llm. Pass --model multiple times when using multiple models.

When --model is omitted, vela setup and vela add call GET /models on the local endpoint and propose local/<local-model-id>=<local-model-id> mappings. For example, qwen2.5:3b becomes local/qwen2.5:3b=qwen2.5:3b.

Diagnostics

vela status separates local PID state, Vela account session state, Vela-side connector status and heartbeat freshness, local /models reachability, and configured model mappings.

vela doctor is first-run friendly. If config is missing it prints:

No connector config found.
Next: run `vela setup`.
Manual path: run `vela login`, then `vela add`.

Network failures are reported by target so Vela API connectivity, local runtime connectivity, auth expiry, and local API key errors do not collapse into a raw fetch failed.

Config And Timeouts

The CLI stores config in $XDG_CONFIG_HOME/vela/connector.json, or ~/.config/vela/connector.json when XDG_CONFIG_HOME is not set. Use VELA_CONNECTOR_CONFIG=/path/to/connector.json to isolate test config.

Operation	Timeout
Local /models health check	3s
Non-streaming response	120s
Streaming first response	60s
Streaming idle gap	30s
Streaming total runtime	5m