Gloamy Documentation

1) What is Gloamy

Gloamy is a secure autonomous agent operating system designed to run agents for real world tasks.

At a high level, Gloamy can:

• Chat with you in your terminal (interactive or one-shot)
• Run persistently for channel based messaging (Telegram, Discord, Slack, Matrix, and more)
• Expose a local gateway for webhook, HTTP, and WebSocket integrations
• Use different model providers (OpenAI, Anthropic, Gemini, local servers, and OpenAI compatible endpoints)
• Execute tools under explicit policy and guardrails (shell, file ops, browser ops, memory)
• Persist memory between sessions (SQLite, Markdown, and more)

2) Core concepts

Gloamy is organized around explicit subsystem contracts:

• Provider: model backends and API integrations
• Channel: messaging transport integrations
• Tool: execution surfaces (shell, file ops, browser ops, integrations)
• Memory: persistence and recall
• Observer: observability and traces
• RuntimeAdapter: runtime isolation
• Peripheral: hardware and board integrations

3) Quick start

A) Install from crates.io (recommended)

cargo install gloamy --locked
gloamy onboard --interactive
gloamy agent

B) Run from source (development)

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

Non-interactive onboarding

Use this only if you already know your exact provider and model.

gloamy onboard --api-key YOUR_API_KEY --provider openai --model gpt-5-mini

4) Running modes

Interactive CLI

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

Daemon (persistent runtime)

Use daemon mode when you want channels and the gateway to stay online.

gloamy daemon

5) Commands

gloamy onboard --interactive
gloamy status
gloamy doctor

gloamy service install
gloamy service start
gloamy service status

6) Configuration (config.toml)

Config is located at ~/.gloamy/config.toml.

api_key = "YOUR_API_KEY"
default_provider = "openai"
default_model = "gpt-5-mini"

[memory]
backend = "sqlite"
auto_save = true

Environment Overrides

Provider overrides happen in this order: GLOAMY_PROVIDER > PROVIDER > default_provider.

7) Providers and Models

• Direct providers (OpenAI, Anthropic, Gemini, etc.)
• Local servers (Ollama, vLLM, etc.)
• OpenAI/Anthropic compatible endpoints

default_provider = "custom:https://your-api.example.com"

8) Channels

Channel settings live under [channels_config] and support Discord, Telegram, Matrix, Slack, and more.

Allowlist Semantics

Empty deny all. "*" allows all. Explicit arrays restrict specific users or contacts.

Examples

[channels_config.telegram]
bot_token = "..."
allowed_users = ["*"]

[channels_config.discord]
bot_token = "..."
allowed_users = ["*"]

11) Operations Runbook

Safe change procedure:

• Back up ~/.gloamy/config.toml
• Apply one logical change at a time
• Run gloamy doctor
• Restart daemon or service
• Verify with status and channel doctor

13) Security Model

Gloamy aims to fail closed.

• Prefer localhost-first binding for gateway
• Use workspace-scoped file access
• Keep channel allowlists deny by default
• Review tool permissions before enabling autonomy

Hardening options include OTP gating ([security.otp]) and Emergency stops ([security.estop]).