Vela Local Connector

@vel4ai/local-connector provides the vela CLI for connecting an OpenAI-compatible local endpoint to Vela through outbound polling. Your local runtime does not need a public inbound URL.

Install

After the package is published, install the CLI globally.

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

To run it once without a global install:

npm exec --package @vel4ai/local-connector -- vela --help

This package intentionally exposes only the vela binary.

Quick Start

Run the guided setup first. It logs in to Vela when needed, asks for the local OpenAI-compatible base URL, reads GET /models, lets you choose detected models, registers the connector, and prints the start command.

vela setup

For common Ollama OpenAI-compatible local setups:

vela setup --local-base-url http://127.0.0.1:11434/v1

Then start the connector and check both local process state and Vela-side state.

vela start --detach
vela status

Use foreground mode when you want logs attached to the terminal.

vela start

Commands

Every command has command-specific help.

vela setup --help
vela login --help
vela add --help
vela start --help
vela doctor --help

Manual setup is still available when you do not want the guided flow.

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 --detach
vela status

vela doctor diagnoses missing config, missing login, local endpoint reachability, Vela API reachability, config file permissions, recorded PID state, and Vela connector status. When setup is incomplete it prints the next command to run.

vela doctor

Model Mapping

--model local/qwen2.5:3b=qwen2.5:3b means:

• local/qwen2.5:3b is the Vela model ID that apps see through Vela.
• qwen2.5:3b is the real local runtime model ID sent to your OpenAI-compatible endpoint.

When --model is omitted, vela setup and vela add read the local GET /models endpoint and propose local/<local-model-id>=<local-model-id> mappings.

Pass --model multiple times when using multiple models.

vela add \
  --local-base-url http://127.0.0.1:11434/v1 \
  --model local/qwen2.5:3b=qwen2.5:3b \
  --model local/llama3.2=llama3.2

Status And Troubleshooting

vela start --detach starts a child process, records its PID, and returns to the shell. It is not an OS service manager. vela status separates:

• local PID state
• Vela account session state
• Vela-side connector status and last heartbeat freshness
• local /models reachability
• configured model mappings

Network errors are grouped by target. For example, Vela API connectivity errors point to internet or --api-base-url, while local runtime errors point to --local-base-url and the local process.

Config And Timeouts

The CLI stores the account session, connector token, local endpoint, model mappings, and last recorded PID in $XDG_CONFIG_HOME/vela/connector.json. If XDG_CONFIG_HOME is not set, it uses ~/.config/vela/connector.json. Use VELA_CONNECTOR_CONFIG=/path/to/connector.json to isolate test config.

The default API target is https://api.vel4.ai. Use --api-base-url during login or setup only when targeting a non-production Vela API.

Local chat calls use explicit timeouts.

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

Development

Build the CLI from the workspace.

pnpm --filter @vel4ai/local-connector build

Run the local mock LLM for development.

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

The mock listens at http://127.0.0.1:1234/v1 and supports:

• GET /v1/models
• POST /v1/chat/completions

Each chat completion request randomly returns one of three sample responses:

• No latency, about 20 characters
• 2 seconds of latency, about 100 characters
• 10 seconds of latency, about 500 characters

Streaming requests use the same random profile, with latency applied before the first stream chunk.

Maintainer Publish Notes

Before publishing, verify that the npm account can publish public packages under the @vel4ai scope.

npm login
pnpm --filter @vel4ai/local-connector test
pnpm --filter @vel4ai/local-connector typecheck
pnpm --filter @vel4ai/local-connector build
cd packages/local-connector
npm pack --dry-run
npm publish --access public

The package uses publishConfig.access=public, files=["dist","README.md"], and a prepack script that builds before packing. After publishing, verify the package with:

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