ShareLLM Client

Share the models on your own machine with your ShareLLM server without opening any inbound ports.

Quick start · Documentation · Contributing · Security · License

---

The ShareLLM Laptop Client is a lightweight worker for the companion ShareLLM server. It advertises the models installed in your local Ollama, picks up matching requests from the server, runs them locally and sends back the results. Every connection is outbound, so it runs fine behind NAT, firewalls and home routers.

Features

• Outbound-only. No listening port, port forwarding, VPN or public IP needed.
• Automatic model discovery. Advertises whatever ollama list shows, refreshed every two minutes.
• One job at a time. Your laptop never runs more than one inference at a time.
• Survives failures. Heartbeats continue during long inferences, result delivery is retried, and lease tokens stop stale results from overwriting newer ones.
• Privacy-aware logging. Logs job IDs and model names, never prompts or generated text.
• Runs natively or in Docker. A hardened container setup for macOS, Windows and Linux, with an optional bundled Ollama.
• Supports the main Ollama APIs. chat, generate, show, embed and embeddings, including the OpenAI-compatible routes on the server.

How it works

sequenceDiagram
    participant C as Laptop Client
    participant S as ShareLLM Server
    participant O as Local Ollama
    C->>O: GET /api/tags (discover models)
    C->>S: register (clientId, models)
    loop every few seconds
        C->>S: heartbeat
    end
    C->>S: claim job (long-poll)
    S-->>C: job + lease token
    C->>O: run request (stream: false)
    O-->>C: JSON response
    C->>S: complete / fail (with lease token)

Loading

See Worker protocol & reliability for the full flow.

Quick start

Prerequisites: Ollama running locally, the worker key of a ShareLLM server, and either Docker or JDK 25 with Maven 3.9+.

With Docker (recommended)

ollama pull llama3.2
cp .env.example .env        # set SHARELLM_SERVER_URL, SHARELLM_WORKER_KEY, SHARELLM_CLIENT_ID
docker compose up -d --build
docker compose logs -f

This works as-is on macOS and Windows with Docker Desktop. On Linux, or to run Ollama in a container too, see Running with Docker.

With Java

# 1. Make a model available locally
ollama pull llama3.2

# 2. Point the client at your server
export SHARELLM_SERVER_URL='https://sharellm.example.org'
export SHARELLM_WORKER_KEY='worker-secret-from-your-server'
export SHARELLM_CLIENT_ID='my-laptop-001'

# 3. Run it
mvn spring-boot:run

Or build and run a standalone JAR:

mvn clean verify
java -jar target/sharellm-client-0.1.0.jar

Tip

No local LLM yet? Run python3 scripts/mock_ollama.py and start the client with OLLAMA_URL=http://localhost:11435. See Development.

Configuration

The client is configured with environment variables. These are the ones most setups need:

Variable	Default	Purpose
SHARELLM_SERVER_URL	http://localhost:8080	ShareLLM server root. Use https:// for anything not on localhost.
SHARELLM_WORKER_KEY	change-me-worker-key	Worker secret configured on the server.
SHARELLM_CLIENT_ID	random	Stable, unique name for this machine.
OLLAMA_URL	http://localhost:11434	Your local Ollama API.

All settings, their validation rules and tuning advice are in the configuration reference. A template is in .env.example. For containers, see the Docker configuration.

Documentation

Topic	Description
Running with Docker	Containerized setup for macOS, Windows and Linux, reaching Ollama, troubleshooting
Configuration reference	Every setting, default value, validation rule and startup warning
Worker protocol & reliability	Registration, heartbeats, leasing, retries and failure handling
Architecture	Clean Architecture layers, package layout and threading model
Quality model (ISO/IEC 25010)	How the design addresses each software quality characteristic
Development guide	Building, testing, the mock Ollama and coding conventions
Security policy	Trust model, known limitations and how to report a vulnerability

Contributing

Contributions are welcome. Read the contributing guide before opening a pull request, and run mvn -B verify locally first: the build requires 100% line coverage. Everyone taking part is expected to follow the Code of Conduct.

Security

Prompts are sent to whichever worker claims the job, so only run workers whose operators you trust with that data. Always use HTTPS for remote servers. See SECURITY.md for the full model.

License

Copyright © 2026 MetaFactory B.V. Licensed under the Apache License, Version 2.0. See NOTICE for attribution and third-party notices.