Sorgente: TUTORIAL.md · raw .md · install/client.sh · install/server.sh

local-ai-bridge-manager — Quick start

Piattaforma gestita da local-ai-bridge-manager.
Base pubblica: https://local-ai-bridge-manager.srv1663152.hstgr.cloud
Host: local-ai-bridge-manager.srv1663152.hstgr.cloud

Client  --Bearer lab_sk_…-->  Manager /v1/*  -->  lab-relay  <==tunnel==  lab-agent  -->  AI locale

Config runtime (non-secret): https://local-ai-bridge-manager.srv1663152.hstgr.cloud/config.json

1 · Ottieni l’accesso (client)

Apri Richiedi accesso oppure chiedi all’admin di creare l’utente.
Copia la private key monouso lab_sk_… (mostrata una sola volta).
Attendi che l’admin Accetti la richiesta (stato approved). Finché è pending l’API risponde 401.

2 · Connessione standard (URL + secret token)

API OpenAI-compatible. Qualsiasi client che accetta Base URL + API key (Hermes Agent, Cursor, Continue, OpenWebUI, LiteLLM, SDK OpenAI, …).

Campo	Valore
API Base URL / OpenAI Base URL	`https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1`
API Key / Secret / Token	`lab_sk_…` (la private key approvata)
Model	id da `GET /v1/models` nel formato `server-name:model-name` (es. `home-gpu:qwen3.6-35b`)

Header HTTP equivalenti:

Authorization: Bearer lab_sk_…
# oppure
X-Api-Key: lab_sk_…

Server AI preferito (se l’admin ti ha assegnato più nodi):

X-Lab-Server: NOME_SERVER

oppure query ?server=NOME_SERVER.

Preferito: scegli il modello già qualificato da /v1/models — il prefisso server-name: seleziona il nodo e viene rimosso prima dell’upstream:

{"model":"home-gpu:qwen3.6-35b","messages":[{"role":"user","content":"ping"}]}

`GET /v1/models` (aggregato per ACL)

Con la tua lab_sk_… il manager elenca automaticamente tutti i modelli di tutti i server a cui la key ha accesso, con id:

server-name:model-name

Accesso key	Cosa vedi in `/v1/models`
`all` (o inherit→all)	tutti i server non `disabled`
`selected`	solo i server in dual-list
`none`	`403`

Risposta OpenAI-compatible:

{
  "object": "list",
  "data": [
    {
      "id": "home-gpu:qwen3.6-35b-a3b-gptq",
      "object": "model",
      "owned_by": "home-gpu",
      "root": "qwen3.6-35b-a3b-gptq"
    },
    {
      "id": "kesi-node-1:laguna-s-2.1",
      "object": "model",
      "owned_by": "kesi-node-1",
      "root": "laguna-s-2.1"
    }
  ]
}

Se un server non risponde, gli altri restano in data; eventuali errori per-server compaiono in errors (campo extra).

Chat / completions / embeddings: usa l’id completo come model. Header X-Lab-Server resta supportato ma non serve se l’id è già server:model.

Hermes Agent

In ~/.hermes/config.yaml (o profilo) un provider custom OpenAI-compatible:

# esempio — adatta nomi al tuo profilo Hermes
model_providers:
  lab-bridge:
    type: openai   # o openai_compatible / custom a seconda versione
    base_url: "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1"
    api_key: "lab_sk_…"   # meglio env: ${LAB_CLIENT_TOKEN}

O via env (molti setup Hermes/OpenAI leggono queste):

export OPENAI_BASE_URL="https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1"
export OPENAI_API_KEY="lab_sk_…"
# opzionale se il client le rispetta:
export LAB_BASE_URL="https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1"
export LAB_CLIENT_TOKEN="lab_sk_…"

Poi seleziona modello = id restituito da /v1/models.

Cursor (e IDE simili)

Settings → Models → OpenAI-compatible / override:

Setting	Valore
Override OpenAI Base URL	`https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1`
OpenAI API Key	`lab_sk_…`
Model name	id da `/v1/models`

Stesso schema per Continue.dev, Cline, Windsurf, client che chiedono solo Base URL + API Key.

curl / SDK

# models
curl -sS -H "Authorization: Bearer lab_sk_…" \
  "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1/models"

# chat
curl -sS -H "Authorization: Bearer lab_sk_…" \
  -H "Content-Type: application/json" \
  "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1/chat/completions" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}],"max_tokens":32}'

Python (openai package):

from openai import OpenAI
client = OpenAI(
    base_url="https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1",
    api_key="lab_sk_…",
)
print(client.models.list())

Non usare token agent lab_ag_… nei client IDE — solo lab_sk_….

3 · Install client CLI (opzionale)

Sostituisci YOUR_LAB_SK con la private key approvata:

curl -fsSL "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/install/client.sh" | bash -s -- --token 'YOUR_LAB_SK'

Cosa fa: scrive ~/.config/local-ai-bridge/client.env (OPENAI_BASE_URL + OPENAI_API_KEY) e il wrapper lab-ai.

lab-ai models
lab-ai chat "ping"
source ~/.config/local-ai-bridge/client.env   # esporta OPENAI_* per altri tool

4 · Install server / agent (un comando, interattivo)

Sull’host GPU (accanto a vLLM/Ollama o altro AI su loopback).
Il manager assegna da solo il token lab_ag_… e ti chiede nome + porta locale da pubblicare via tunnel.

curl -fsSL "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/install/server-setup.sh" | bash

Durante il setup scegli:

Nome server (default = hostname)
Porta locale AI (tunnel target su 127.0.0.1):
- default consigliato: 18000 (poco conflitto)
- alt 1: 11434 (Ollama tipica)
- alt 2: 8000 (vLLM tipica)
- oppure porta custom / rilevata in ascolto
Relay control (default 127.0.0.1:17422 — spesso SSH LocalForward)

Lo script verifica che sulla porta ci sia un’API AI (/v1/models, Ollama /api/tags, …): mostra engine/modelli.
Se non trova nulla → errore + scan porte + suggerimenti (AI spenta / altra porta).
Poi enroll, install agent e smoke passo-passo (manager, AI locale, relay TCP, processo agent, gateway 401).

Avanzato / non-interattivo:

curl -fsSL "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/install/server-setup.sh" | bash -s -- \
  --yes --name 'home-gpu' --port 18000

Oppure token già creato in Admin:

curl -fsSL "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/install/server.sh" | bash -s -- \
  --token 'YOUR_LAB_AG' \
  --name 'home-gpu' \
  --local '127.0.0.1:18000' \
  --relay '127.0.0.1:17422'

Flag setup	Default	Significato
(interattivo)	—	enroll API + domande nome/porta
`--port`	`18000`	porta AI locale → tunnel
`--local`	`127.0.0.1:PORT`	host:port esplicito
`--relay`	`127.0.0.1:17422`	control relay
`--enroll-code`	(se admin lo richiede)	codice condiviso

Il relay pubblico e il tunnel SSH vanno già operativi (vedi deploy local-ai-bridge). L’agent fa solo outbound verso il relay.
Upstream manager (data plane): http://176.9.10.220/lab-ai
API enroll: https://local-ai-bridge-manager.srv1663152.hstgr.cloud/api/enroll/server

5 · Quick test

curl -sS -H "Authorization: Bearer lab_sk_…" \
  "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1/models" | head

curl -sS -H "Authorization: Bearer lab_sk_…" \
  -H "Content-Type: application/json" \
  "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1/chat/completions" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}],"max_tokens":32}'

6 · Admin

Azione	URL
Login	https://local-ai-bridge-manager.srv1663152.hstgr.cloud/login
Utenti (vedi tutti / accetta / revoca)	https://local-ai-bridge-manager.srv1663152.hstgr.cloud/admin
Cambia password	https://local-ai-bridge-manager.srv1663152.hstgr.cloud/admin/password
Tutorial (questa pagina)	https://local-ai-bridge-manager.srv1663152.hstgr.cloud/tutorial
Config pubblica JSON	https://local-ai-bridge-manager.srv1663152.hstgr.cloud/config.json

Sicurezza:

Cookie admin: HttpOnly + Secure + SameSite=Strict
Private key: hash SHA-256 in DB, plain solo monouso in UI
Gateway: solo utenti approved
Non mettere mai LAB_AGENT_TOKEN / lab_ag_… nei client

7 · Troubleshooting

Sintomo	Causa tipica
`401 unauthorized`	Key sbagliata, utente `pending`/`revoked`, header mancante
`404` su `/v1/...`	Base URL senza `/v1` oppure path doppio (`/v1/v1`)
Client “invalid URL”	Usa `https://local-ai-bridge-manager.srv1663152.hstgr.cloud/v1` (con `/v1`), non solo l’host
`502` / upstream unreachable	lab-agent offline o relay non raggiunto
`503` upstream not configured	`LAB_UPSTREAM_TOKEN` assente sul manager
Cert / “not secure”	Usa solo HTTPS su questo host (reverse proxy + certificato), non HTTP o IP grezzo

Health manager:

curl -fsS "https://local-ai-bridge-manager.srv1663152.hstgr.cloud/healthz"

Tutorial