Quickstart

This guide will walk you through setting up Gambiarra, creating your first room, and making your first LLM request through the shared pool.

Before starting, make sure you have a local LLM running (Ollama, LM Studio, etc.). If you don’t have one yet, install Ollama and run ollama pull llama3.

Prerequisites

A local LLM server (Ollama, LM Studio, LocalAI, etc.)
Node.js 18+ or Bun 1.0+ (for SDK usage)
Two or more machines on the same network (optional, but ideal for testing)

Setup

Install the CLI

Install the Gambiarra CLI using the standalone installer:

curl -fsSL https://raw.githubusercontent.com/arthurbm/gambiarra/main/scripts/install.sh | bash

Verify the installation:

gambiarra --version

Start the hub server

The hub is the central coordinator for all rooms and participants. Start it on any machine in your network:

gambiarra serve --port 3000 --mdns

You should see output like:

Hub started at http://0.0.0.0:3000
Health check: http://0.0.0.0:3000/health
mDNS: http://your-machine.local:3000
      Service: gambiarra-hub-3000._gambiarra._tcp.local

Press Ctrl+C to stop

The --mdns flag enables automatic discovery on your local network. Clients can find the hub without knowing its IP address.

Keep this terminal running. The hub needs to stay active for participants to communicate.

Create a room

Open a new terminal and create a room:

gambiarra create --name "My First Room"

Output:

Room created!
  Code: ABC123
  ID: xK3mP9n2L4qW

Share the code with participants to join.

The room code (like ABC123) is what others will use to join your room. Share it with your team!

Optional: Password protection

You can protect your room with a password:

gambiarra create --name "Secure Room" --password mySecret123

Join with your LLM

Now join the room with your local LLM endpoint. This makes your LLM available to others in the room.

Ollama
LM Studio
LocalAI
Custom

gambiarra join ABC123 \
  --endpoint http://localhost:11434 \
  --model llama3 \
  --nickname "My Laptop"

gambiarra join ABC123 \
  --endpoint http://localhost:1234 \
  --model gpt-4 \
  --nickname "My Desktop"

gambiarra join ABC123 \
  --endpoint http://localhost:8080 \
  --model llama3 \
  --nickname "My Server"

gambiarra join ABC123 \
  --endpoint http://192.168.1.100:8000 \
  --model your-model \
  --nickname "GPU Server"

Output:

Detected specs: Intel Core i7-9700K, 32GB RAM, NVIDIA RTX 3080 (10GB)

Joined room ABC123!
  Participant ID: kJ9mN2p4L8qR
  Nickname: My Laptop
  Model: llama3
  Endpoint: http://localhost:11434

Your endpoint is now available through the hub.
Press Ctrl+C to leave the room.

The participant will automatically send health checks every 10 seconds to stay online.

If the room is password-protected, add --password mySecret123 to the join command.

Use the SDK in your application

Now that you have a hub running and a participant joined, you can use the SDK to interact with the shared LLM pool.Install the SDK in your project:

npm install gambiarra-sdk ai

Create a file app.ts:

app.ts

import { createGambiarra } from "gambiarra-sdk";
import { generateText } from "ai";

const gambiarra = createGambiarra({
  roomCode: "ABC123",
  hubUrl: "http://localhost:3000",
});

const result = await generateText({
  model: gambiarra.any(),
  prompt: "What is Gambiarra?",
});

console.log(result.text);

Run it:

bun run app.ts
# or
npx tsx app.ts

You should see a response from the LLM!

What just happened?

Let’s break down what happened:

Hub started - The central coordinator started on port 3000
Room created - A virtual room with code ABC123 was created
Participant joined - Your local LLM registered as a participant in the room
SDK connected - Your application connected to the hub and made a request
Request routed - The hub routed your request to an available participant
Response returned - The participant’s LLM processed the request and returned the result

Your App                     Hub                    Participant
   │                          │                          │
   │  generateText(...)       │                          │
   │ ────────────────────────►│                          │
   │                          │  Proxy request           │
   │                          │ ────────────────────────►│
   │                          │                          │
   │                          │  LLM response            │
   │                          │ ◄────────────────────────│
   │  Response                │                          │
   │ ◄────────────────────────│                          │

Try different routing patterns

Gambiarra supports three routing strategies:

1. Any available participant (random)

Use any online participant:

const result = await generateText({
  model: gambiarra.any(),
  prompt: "Hello!",
});

2. Specific model

Route to the first participant with a specific model:

const result = await generateText({
  model: gambiarra.model("llama3"),
  prompt: "Hello from llama3!",
});

3. Specific participant

Route to a specific participant by ID:

const result = await generateText({
  model: gambiarra.participant("kJ9mN2p4L8qR"),
  prompt: "Hello from specific participant!",
});

Streaming responses

Gambiarra fully supports streaming responses:

import { createGambiarra } from "gambiarra-sdk";
import { streamText } from "ai";

const gambiarra = createGambiarra({ roomCode: "ABC123" });

const stream = await streamText({
  model: gambiarra.model("llama3"),
  prompt: "Write a haiku about TypeScript",
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

List available models

You can programmatically list all participants and models in a room:

import { createGambiarra } from "gambiarra-sdk";

const gambiarra = createGambiarra({ roomCode: "ABC123" });

// List all participants
const participants = await gambiarra.listParticipants();
console.log(participants);
// [
//   {
//     id: "kJ9mN2p4L8qR",
//     nickname: "My Laptop",
//     model: "llama3",
//     endpoint: "http://localhost:11434",
//     status: "online",
//     ...
//   }
// ]

// List available models (OpenAI-compatible format)
const models = await gambiarra.listModels();
console.log(models);
// [
//   {
//     id: "kJ9mN2p4L8qR",
//     nickname: "My Laptop",
//     model: "llama3",
//     endpoint: "http://localhost:11434"
//   }
// ]

Monitor with the Terminal UI

Gambiarra includes a beautiful Terminal UI for real-time monitoring. If you just run gambiarra without arguments, it opens the TUI:

gambiarra

From the TUI, you can:

See all available rooms
View participants and their health status
Monitor request activity in real-time
Create and join rooms interactively

The TUI is perfect for debugging and monitoring your Gambiarra network.

Working with multiple participants

The real power of Gambiarra comes from multiple participants. Open another terminal (or use another machine) and join the same room with a different model:

# Terminal 2 (or another machine)
gambiarra join ABC123 \
  --endpoint http://localhost:11434 \
  --model mistral \
  --nickname "Secondary GPU"

Now when you use gambiarra.any(), requests will be randomly distributed across both participants. When you use gambiarra.model("mistral"), requests will go to the second participant.

List all rooms

See all available rooms on a hub:

gambiarra list

Output:

Available rooms:
  - ABC123 (2 participants)
  - XYZ789 (1 participant)

Clean up

When you’re done:

Stop participants - Press Ctrl+C in the terminal where you ran gambiarra join
Stop the hub - Press Ctrl+C in the terminal where you ran gambiarra serve

Rooms are stored in memory, so they’ll be cleared when the hub stops.

Next steps

CLI reference

Learn about all available CLI commands

SDK reference

Explore advanced SDK features

Architecture

Understand how Gambiarra works

Troubleshooting

Common issues and solutions

Get Started

CLI Commands

SDK

Terminal UI

Guides

Advanced

Prerequisites

Setup

Optional: Password protection

What just happened?

Try different routing patterns

1. Any available participant (random)

2. Specific model

3. Specific participant

Streaming responses

List available models

Monitor with the Terminal UI

Working with multiple participants

List all rooms

Clean up

Next steps

CLI reference

SDK reference

Architecture

Troubleshooting

Build docs developers (and LLMs) love

Get Started

CLI Commands

SDK

Terminal UI

Guides

Advanced

​Prerequisites

​Setup

​Optional: Password protection

​What just happened?

​Try different routing patterns

​1. Any available participant (random)

​2. Specific model

​3. Specific participant

​Streaming responses

​List available models

​Monitor with the Terminal UI

​Working with multiple participants

​List all rooms

​Clean up

​Next steps

CLI reference

SDK reference

Architecture

Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Setup

Optional: Password protection

What just happened?

Try different routing patterns

1. Any available participant (random)

2. Specific model

3. Specific participant

Streaming responses

List available models

Monitor with the Terminal UI

Working with multiple participants

List all rooms

Clean up

Next steps