Intro

When the claws 🦞 are asleep the gloamies 🦉 come out to play !

Hi I'm Gloamy, I execute tasks on your behalf without deleting your stuff, leaking your private business, oh and I'm lightweight unlike that damn lobster (openclaw).

Overview

Gloamy is built around explicit subsystem contracts:

• Provider for model backends
• Channel for messaging platforms
• Tool for execution surfaces
• Memory for persistence and recall
• Observer for observability
• RuntimeAdapter for runtime isolation
• Peripheral for boards and device integrations

The project goal is simple: Local first agents for real-world tasks

What Gloamy Does

Gloamy can:

• chat with you in your terminal
• stay running in the background to handle messages
• control apps on your pc with permissions
• let desktop and external API clients connect through the gateway
• use different AI models to answer questions
• run tools and scripts on your computer or online, safely
• remember things between sessions
• connect to devices and smart hardware

Out of the box, the runtime supports:

• local CLI usage
• channel-based operation through providers such as Telegram, Discord, Slack, Matrix, WhatsApp, iMessage, Email, IRC, Nostr, and others
• OpenAI-compatible and non-OpenAI model providers
• SQLite, Markdown, Lucid, PostgreSQL, and no-op memory modes

Project Shape

High-level repository map:

• src/main.rs: CLI entrypoint and command routing
• src/lib.rs: shared exports and command enums
• src/agent/: orchestration loop
• src/config/: config schema, loading, merging, env overrides
• src/providers/: model provider implementations and factory wiring
• src/channels/: channel integrations
• src/tools/: tool execution surface
• src/memory/: memory backends
• src/security/: policy, pairing, secret handling
• src/gateway/: HTTP and websocket gateway
• src/runtime/: runtime adapters
• src/peripherals/: hardware integrations
• desktop/: Tauri + Vue desktop application
• docs/: operator, reference, and contribution docs

Key Properties

• Trait-driven architecture
• Secure-by-default runtime behavior
• Small binary and low runtime overhead
• Explicit config and CLI contracts
• Swappable providers, channels, memory backends, and tools
• Deterministic, Rust-first deployment model

Optional Robot

The repository also includes crates/robot, a standalone robot-control crate for motion, sensing, speech, vision, simple robot expression, and safety-gated drive control.

Use it when you want to experiment with Raspberry Pi or robot hardware integrations without wiring those surfaces directly into the main runtime. It is a workspace member, but it is not auto-registered into gloamy's core tool factory.

Start here:

• crates/robot/README.md for the crate surface and integration model
• crates/robot/robot.toml for the sample configuration
• crates/robot/PI5_SETUP.md for Raspberry Pi 5 setup notes

Quick Start

Prerequisites

You need:

• a working Rust toolchain
• standard platform build tools
• an API key or local model endpoint, depending on your provider

On macOS:

xcode-select --install

On Debian or Ubuntu:

sudo apt install build-essential pkg-config

Install Rust:

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

Verify:

rustc --version
cargo --version

Install

Install from crates.io:

cargo install gloamy --locked

Then run full onboarding:

gloamy onboard --interactive

If you prefer to run from source, clone the repository and start onboarding:

git clone https://github.com/iBz-04/gloamy.git
cd gloamy
cargo run -- onboard --interactive

The crates.io install is the recommended default for end users. The source path is better when you want to develop, patch, or test unreleased changes.

The full onboarding flow lets you:

• choose your provider and default model
• configure channels
• set memory behavior
• create workspace identity files
• avoid partial setup drift

After onboarding, start a direct CLI session:

cargo run -- agent

If you want persistent channel operation after setup:

cargo run -- daemon

Bootstrap Script

If you prefer the bootstrap path:

./bootstrap.sh --interactive-onboard

Useful bootstrap variants:

./bootstrap.sh
./bootstrap.sh --install-system-deps --install-rust
./bootstrap.sh --prefer-prebuilt
./bootstrap.sh --prebuilt-only
./bootstrap.sh --docker

Reference: docs/one-click-bootstrap.md

Non-Interactive Setup

If you already know exactly what you want, you can skip the full wizard:

cargo run -- onboard --api-key YOUR_OPENAI_KEY --provider openai --model gpt-5-mini

This path is faster, but the interactive onboarding flow is the better default for first setup.

Migrating from OpenClaw

Gloamy can import memory from an existing OpenClaw workspace into your current Gloamy workspace.

Preview the migration first:

cargo run -- migrate openclaw --dry-run

Run the import:

cargo run -- migrate openclaw

Use a custom OpenClaw workspace path if needed:

cargo run -- migrate openclaw --source /path/to/openclaw/workspace

What the migration does:

• reads importable memory from ~/.openclaw/workspace by default
• imports entries from memory/brain.db, MEMORY.md, and memory/*.md
• skips unchanged entries on re-run and renames conflicting keys deterministically
• creates a backup of the target Gloamy memory before writing

What it does not do:

• it does not migrate arbitrary workspace files
• it does not convert OpenClaw config into Gloamy config.toml

If you want a safe preview of the candidate entries without writing data, use --dry-run.

Desktop App

This repository also includes a desktop application in desktop/, built with Tauri (Rust backend) and Vue 3 (frontend).

Use the desktop app for the primary UI, and use the gateway for webhook/API access.

If you want to run the desktop UI locally:

cd desktop
pnpm install
pnpm tauri dev

For desktop-specific setup, development, and packaging details, see desktop/README.md.

Running Modes

Interactive CLI

Start a direct chat session:

cargo run -- agent

Run a one-shot prompt:

cargo run -- agent -m "Summarize today's logs"

Override provider and model for one run:

cargo run -- agent --provider openai --model gpt-5-mini -m "hello"

Daemon

Run the long-lived runtime:

cargo run -- daemon

The daemon starts:

• configured channels
• gateway server
• heartbeat
• scheduler

Use this mode when you want Telegram or other channels to stay online.

Gateway

Run only the local gateway:

cargo run -- gateway

The gateway exposes HTTP, webhook, and websocket endpoints for external integrations. It no longer serves a browser dashboard.

Channels Only

Run the configured channels without the full daemon stack:

cargo run -- channel start

First-Time Configuration

The primary setup command is:

gloamy onboard

Common variants:

gloamy onboard --interactive
gloamy onboard --channels-only
gloamy onboard --force
gloamy onboard --api-key YOUR_KEY --provider openai --model gpt-5-mini

If you already have a config and only want to wire channels, use:

gloamy onboard --channels-only

Channels

Gloamy supports multiple inbound and outbound channels. Channel setup is stored in config, and the daemon uses that config at runtime.

Typical flow:

1. Run gloamy onboard --channels-only
2. Configure Telegram, Discord, Slack, WhatsApp, or another channel
3. Start gloamy daemon
4. Verify with gloamy status and gloamy channel doctor

Important operational note:

• gloamy agent is for direct CLI use
• gloamy daemon is what you run for persistent channel operation

Canonical reference: docs/channels-reference.md

Configuration

Default config location:

~/.gloamy/config.toml

Default workspace:

~/.gloamy/workspace

Minimal example:

api_key = "sk-..."
default_provider = "openai"
default_model = "gpt-5-mini"
default_temperature = 0.7

[memory]
backend = "sqlite"
auto_save = true
embedding_provider = "none"
vector_weight = 0.7
keyword_weight = 0.3

Notes:

• default_provider controls the main runtime provider
• default_model controls the default model for CLI, channel, and daemon flows
• default_temperature may be ignored by some providers or models
• several settings can also be overridden by environment variables

Canonical reference: docs/config-reference.md

Provider Model

Gloamy supports:

• direct providers such as OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek, Venice, GLM, Qwen, and others
• OpenAI-compatible custom endpoints
• provider aliases and routed model configuration
• subscription-native auth flows for supported providers

Examples:

gloamy agent --provider openai --model gpt-5-mini -m "hello"
gloamy agent --provider anthropic -m "hello"
gloamy agent --provider openai-codex -m "hello"

References:

• docs/providers-reference.md
• docs/custom-providers.md

Security Model

Gloamy is designed to fail closed where practical.

Important defaults:

• localhost-first binding
• explicit pairing for gateway auth flows
• workspace-scoped file access
• deny-by-default channel allowlists
• encrypted secret support
• explicit security policy for tool and command execution

Operational guidance:

• do not expose the gateway directly without understanding the bind and tunnel settings
• use allowlists for channels instead of wide-open routing
• keep secrets in config or environment variables, not in workspace files
• review tool and command permissions before enabling broad autonomy

References:

• docs/security/README.md
• docs/operations-runbook.md
• docs/troubleshooting.md

Memory

Supported memory backends include:

• SQLite
• Markdown
• Lucid
• PostgreSQL
• none

SQLite is the usual default because it gives:

• local persistence
• keyword and vector search support
• practical low-friction setup

Reference: docs/config-reference.md

Commands You Will Actually Use

gloamy status
gloamy doctor
gloamy channel doctor
gloamy agent
gloamy daemon
gloamy gateway
gloamy onboard --interactive
gloamy onboard --channels-only
gloamy auth status
gloamy service install
gloamy service status
gloamy service restart

Canonical command reference: docs/commands-reference.md

Development

Recommended local validation:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

Preferred full local validation path when available:

./dev/ci.sh all

Useful development commands:

cargo run -- status
cargo run -- doctor
cargo run -- agent -m "hello"
cargo run -- daemon

If you are working on docs, start here:

• docs/README.md
• docs/SUMMARY.md

Documentation Map

Start from the docs hub:

• Docs hub: docs/README.md
• Unified TOC: docs/SUMMARY.md
• Getting started: docs/getting-started/README.md
• Reference: docs/reference/README.md
• Operations: docs/operations/README.md
• Security: docs/security/README.md
• Hardware: docs/hardware/README.md
• Contributing workflow: docs/pr-workflow.md

High-signal runtime references:

• docs/commands-reference.md
• docs/providers-reference.md
• docs/channels-reference.md
• docs/config-reference.md
• docs/operations-runbook.md
• docs/troubleshooting.md

Official Repository

Official source of truth:

• https://github.com/iBz-04/gloamy

If you encounter impersonation or a misleading fork, open an issue in the official repository.

Contributing

If you want to contribute:

• review AGENTS.md for repository engineering expectations
• read docs/pr-workflow.md
• use docs/reviewer-playbook.md for review standards

Good entry points:

• new provider in src/providers/
• new channel in src/channels/
• new tool in src/tools/
• new memory backend in src/memory/
• new observer in src/observability/

License

Gloamy is licensed under MIT.

Contact

reach me @ issakaibrahimrayamah@gmail.com