Get Started — FeLLAMA

Prerequisites

Rust Toolchain

Required

Rust 2024 edition. Install via rustup.rs.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

LLM Endpoint

Required

Any OpenAI-compatible API. Local (llama.cpp, vLLM, Ollama) or remote (OpenAI, Anthropic via proxy).

Browserless

Optional — for web automation

Required only for the SmartWeb agent. Provides headless Chrome via CDP.

docker run -p 3000:3000 browserless/chrome

Embedding Model

Optional — for vector search

Required only for the Vector DB. Any embedding endpoint serving /v1/embeddings.

Clone & Build

Clone the repository and run the setup script. It checks prerequisites, builds all release binaries, and creates your configuration directory.

bash

git clone https://github.com/rexf/fellama.git
cd fellama
./setup.sh

Verify Rust and Cargo are installed
Build all binaries in release mode
Create ~/.fellama/ directory
Generate default config.toml
Generate default url_rules.toml

Manual build: If you prefer not to use the script, run cargo build --release directly. Binaries will be in target/release/.

Configure

Edit ~/.fellama/config.toml to point FeLLAMA at your LLM endpoint. This is the minimum configuration needed.

~/.fellama/config.toml

# Point to your OpenAI-compatible LLM API
endpoint = "http://localhost:8000/v1"

# Model name as known by your endpoint
model = "your-model-name"

# Controls LLM creativity (0.0 = deterministic, 1.0 = creative)
agent_temperature = 0.6

# Optional: enable browser automation
# browserless_endpoint = "ws://localhost:3000"

# Optional: enable detailed logging
# enable_trace_log = true

See the Configuration Reference for all available options.

Start the Server

FeLLAMA runs as a persistent background service. Start the server in one terminal:

terminal 1

cargo run --release --bin fellama-server

Connect with the CLI

In a second terminal, launch the TUI client to connect to the running server:

terminal 2

cargo run --release --bin fellama

The CLI opens a terminal UI with a virtual shell. Type your request and FeLLAMA will decompose it, dispatch agents, and stream results back.

Example Commands

You can also run agents directly from the command line without the server:

Web research:

bash

cargo run --release --bin fellama-smartweb-agent -- \
  --request "Find the latest Rust async runtime benchmarks" \
  --human

Summarize a document:

bash

cargo run --release --bin fellama-summarizer -- \
  --file report.pdf \
  --output-format markdown \
  --human

Extract spreadsheet data:

bash

cargo run --release --bin fellama-spreadsheet-extractor -- \
  --file data.xlsx \
  --human

Troubleshooting

Build fails with missing dependencies

Ensure you have a C compiler and OpenSSL dev headers. On macOS: xcode-select --install. On Ubuntu: sudo apt install build-essential libssl-dev pkg-config.

LLM connection refused

Verify your endpoint in config.toml is correct and the LLM server is running. Test with: curl http://localhost:8000/v1/models

SmartWeb agent can't connect to browser

Ensure Browserless is running: docker run -p 3000:3000 browserless/chrome. Set browserless_endpoint = "ws://localhost:3000" in config.toml.

Enable debug logging

Set enable_trace_log = true in config.toml. Logs appear in ~/.fellama/ — single-turn agents write to <binary-name>.log, multi-turn agents to <session-id>/trace.log.