Support

Let’s get you unstuck. Start with the checks below, then share a small, reproducible report if the problem remains.

Start here

What happened	What to try
Installation failed	Check your platform and prerequisites in Install Lemon
The first chat cannot start	Run lemon config validate, lemon secrets status, then lemon setup provider
A runtime or tool behaves unexpectedly	Run lemon doctor --verbose and keep the relevant error
You need a diagnostic bundle	Run lemon doctor --bundle, then review the zip before sharing
You found a vulnerability	Follow security reporting privately

For a source checkout, use ./bin/lemon in place of lemon. A successful configuration check does not guarantee a provider request will succeed; the first-conversation quickstart walks through a complete turn.

Report a problem

Open a bug report with:

• your Lemon version or commit, operating system, and install method;
• the interface you used and the smallest steps that reproduce the problem;
• what you expected, what happened, and relevant redacted error output;
• a reviewed support bundle when it helps explain the failure.

Keep credentials, private prompts, memory contents, and tool output out of public issues. Diagnostic bundles are designed to redact sensitive data, but review attachments before posting them.

Find the right reference

• Channel support: Telegram and Discord boundaries.
• Web, browser, and media: supported workflows and previews.
• Automation and cron: scheduling expectations.
• Diagnostic bundle details: what each diagnostic contains.
• Logs: collect a focused trace when requested.
• Release support policy: detailed release criteria.

The sections below distinguish supported behavior from preview implementation. A feature appearing in the code or diagnostics does not by itself promote it to a stable support guarantee.

Supported for 1.0

Initial stable 1.0 support targets:

• source installs on machines with supported Elixir and Erlang/OTP versions

• Linux x86_64 release tarballs published by the Lemon release workflow

• provider setup through documented configuration and secrets commands

• runtime startup through ./bin/lemon start and ./bin/lemon daemon, plus ./bin/lemon-tui and release scripts

• Web health and session pages

• first-party text web tools such as web search/fetch when used from supported agent runs

• doctor diagnostics and redacted support bundles

• preview checkpoint diagnostics through Telegram/Discord /checkpoint status/events/diff/restore controls and TUI /checkpoint diff and /checkpoint restore, with redacted lifecycle event counts/history, pushed active-run event notices, support-bundle metadata, and rollback command guidance. Shared checkpoint storage and filesystem rollback are owned by LemonCore.Checkpoint; channel restore requires an explicit confirmation token or slash-command boolean.

• preview LSP diagnostics through the model-facing lsp_diagnostics tool, opt-in write/edit/patch baseline/delta checks, and lsp_diagnostics.json in support bundles. LemonLsp.ServerManager is a supervised BEAM status, stdio session, initialize, JSON-RPC framing, and diagnostic-notification manager for the known language-server registry. The preview reports checker/server capability, redacted session health, redacted document URI hashes/counters, and redacted diagnostic batch counts only; support bundles omit file paths, executable paths, raw session ids, file contents, workspace roots, diagnostic output, and server I/O. See docs/tools/lsp.md for checker and language-server install commands.

• preview generated-media job observability through Telegram/Discord /media status and media_diagnostics.json in support bundles. The preview reports job type/status counts, artifact counts/bytes, cleanup policy, prompt hashes, and artifact path hashes only; support surfaces omit prompts, raw artifact paths, generated bytes, provider responses, channel message bodies, and API credentials. LemonMedia.MediaJobSupervisor owns the preview Task.Supervisor boundary for queued/running/completed/failed media job lifecycle updates and emits redacted PubSub events for operator surfaces.

• Telegram/Discord setup diagnostics through channel_diagnostics.json in support bundles. The bundle reports enabled/configured state, binding counts, topic binding counts, file-transfer settings, generated-file auto-send settings, Telegram voice-transcription configuration, Discord bot-message policy, and allowlist counts without raw tokens, secret names, channel ids, or message bodies.

• browser tool progress status. Browser requests emit redacted current_action updates for Web/TUI/Telegram/Discord status surfaces with method, phase, timeout, safe counts, artifact flags, and hashed host metadata only; raw URLs, selectors, typed text, cookie values, page text, screenshot bytes, and artifact paths are omitted.

• memory-provider diagnostics through memory_diagnostics.json in support bundles. The bundle reports provider count, enabled provider count, provider ids, source labels, supported scopes, timeout shape, and module-load state without memory document contents, raw provider config, secret values, prompts, tool output, or provider error payloads.

• BEAM runtime capacity diagnostics through root status. The response includes process, port, atom, and run-queue counters plus limits so operators can distinguish Lemon runtime pressure from provider or channel issues; missing optional supervisors fail closed to zero counts instead of crashing status.

• usage diagnostics through read-only usage.status. The response reads the same current summary maintained by usage.cost, reports run/token/cost counts, per-provider request/token/cost rows, quota status, remaining quota estimates, and cleanup flags without returning prompts, responses, or secret values.

• canonical spend accounting through read-only usage.records. Request {fromMs, toMs, runId?, sessionKey?, cursor?, limit?} with a half-open millisecond range [fromMs, toMs); limit defaults to 100 and is bounded to 1–500. The response is {records, nextCursor, incomplete}. Each record contains id, runId, sessionKey, agentId, atMs, model, provider, inputTokens, outputTokens, totalTokens, costUsd and priceKnown. Exhaust every cursor page; ordering is stable by occurrence time and ID, and a cursor cannot be reused with different range/run/session filters. Native completed assistant calls retain their actual response price, including tier pricing, and native run identity across local and named-node execution. Durable run/occurrence IDs prevent replayed completions from double billing, including after ledger restart. costUsd: null, priceKnown: false means unknown, not free; a known zero price is 0 with priceKnown: true. Historical missing occurrence attribution/time remains incomplete (agentId or atMs can be null); aggregate-only history is not assigned to invented runs or sessions. Native default zero prices on uncatalogued models remain unknown unless their actual usage explicitly attests a known price. Store/query failures return errors, never an empty successful page. Spend enforcement must fail closed on unavailable or incomplete accounting and cannot derive provider-account or product-user authority from provider/model labels. usage.cost remains a bounded display of known-cost subtotals, exposes knownCostSubtotal/incomplete, and is not an enforcement ledger. No prompts, response bodies, filesystem paths or credentials appear in records.

• config diagnostics through config.get and config.set. Stored config keys that look like API keys, tokens, passwords, secrets, credentials, or private keys are returned as bounded redaction objects in single-key and full-config reads, and sensitive config.set responses do not echo the submitted value.

• model catalog diagnostics through read-only models.list. The response includes provider/capability counts, source metadata, and cleanup flags while omitting credential and secret values.

• agent directory diagnostics through agent.directory.list and agents.list. These responses include compact agent/session summaries and cleanup flags without returning message bodies, credentials, or secret values.

• Hermes-compatible final-answer MEDIA:<project-relative-path> directives for Telegram and Discord. Lemon resolves these at router finalization time into the existing auto_send_files delivery path only when the target is an existing regular file inside the run working directory; symlink escapes, missing files, and out-of-project paths are ignored, and the directive line is stripped from the channel-facing text.

• preview durable goal status, one-shot continuation, one supervised judge tick, max-continuation budgets, and persisted auto-loop scheduling exposed through TUI /goal and Telegram/Discord /goal controls, goal lifecycle events, and redacted support-bundle metadata. This is bounded supervised loop plumbing with a dev/prod router-backed judge default, deterministic proof through the real router run process, persisted-auto scheduler proof through the same path, and provider-backed live model-judge proof. Richer channel-visible loop behavior remains preview before full persistent-goal parity.

• preview durable kanban board/task state, JSON-RPC board/task/archive/dispatcher methods, model-facing kanban tool, supervised dispatcher leases, per-task git worktree worker cwd for git-backed boards, redacted control-plane board visibility, TUI /kanban board/task/archive/dispatcher controls, Telegram /kanban commands, Discord /kanban slash commands, and redacted support-bundle diagnostics.

• bugs with reproduction steps on supported source or release-runtime paths

Channel Support

Telegram and Discord are stable 1.0 remote chat channels for text-first agent runs. The TUI, Web UI, and control plane are stable first-party local interfaces. In control-plane mode, the TUI renders approval events as notifications; MCP OAuth approval requests include the authorization URL plus resource, scope, and redirect context, and MCP sampling approval requests include redacted request hash, model, token, message, role, and content-kind metadata. Operators can resolve pending approvals from the terminal with /approve [n] [once|session|agent|global] or /deny [n]; /approvals refreshes the current pending approval snapshot through exec.approvals.get. Here n is the 1-based list index. Approval timeouts also arrive as exec.approval.resolved notifications with decision: "timeout" so terminal operators see when a pending request expired. An approval whose run or session ended is expired at once with decision: "expired"; the TUI shows approval expired … — the run ended, and answering it later is refused as expired.

lemon channels inspects redacted Telegram and Discord configuration: enabled state, credential configuration, binding counts, allowlist counts, and registered transports. Its --json output contains the same status map. Doctor channel checks are configuration-only: Telegram configuration and voice transcription settings, plus Discord configuration and declared Message Content Intent. Discord text support includes mention-triggered prompts, rendering, long-output chunking, tool status, text-file attachments, and public-thread prompt/reply. Optional manual Telegram and Discord live matrices remain available for real-service smoke checks; their result files are not read by Lemon. Active cron runs can be aborted by cron run id through the control-plane cron.abort method, the model-facing cron tool abort action, or TUI /cron abort <run-id>. Abort routes to the underlying Lemon run cancellation when that run is still alive, persists the cron run as aborted, and does not retry the run.

The control-plane cron.status surfaces cron scheduler health as aggregate counters for active run locks, retry runs, suppressed scheduled slots, stale-run recoveries, and scheduled retries, plus next/last run timestamps and status/trigger/audit count maps. Those counters come from the same durable run and audit stores used by support bundles, so operators can see when BEAM scheduling is intentionally holding a slot instead of launching a duplicate run. It also reports paused and pausedAtMs for the durable global cron pause (lemon cron pause --all), separately from restorationPending, the scheduler's startup-restoration hold. Even after resume clears paused, scheduled dispatch, wake triggers, and retries wait until pending restoration succeeds. Explicit manual run_now requests remain allowed during that hold; see pausing all cron jobs.

Cron lifecycle actions also write durable operator audit events to :cron_audit_events. The control-plane cron.audit read method returns raw operator IDs for authorized clients shows the most recent lifecycle audit entries, and the WebSocket event bridge emits cron.audit updates. Support bundles include only redacted audit counts, action counts, recent action shape, reason hashes, ID hashes, and changed-field names.

Cron creation and updates accept 5-field cron expressions plus supported operator shorthands such as every 30m, hourly, every 2h, daily at 9am, weekdays at 09:30, and weekly monday at 8am. Lemon stores the normalized 5-field cron expression. Interval shorthands must divide the enclosing cron field exactly, and unsupported free-form schedule text is rejected through the normal cron validation path.

Control-plane operators can create no-agent command cron jobs with command instead of agentId/sessionKey/prompt. These jobs run as supervised local shell commands under CronManager, persist output/error in cron run history, and do not create LemonRouter runs or channel summaries. cron.update preserves the original target type: command jobs can update command, cwd, and env, while prompt jobs can update prompt. The model-facing cron tool remains prompt-job scoped.

Web, Browser, and Media Tools

Stable 1.0 support covers first-party text web search/fetch behavior when the run is reproducible on a supported source or release-runtime install. Browser automation is now a preview first-party surface through supervised browser_* coding-agent tools backed by the local Node/Playwright driver. Visual generated media, image analysis, and voice or TTS behavior remain preview or out of scope unless a release note explicitly promotes a narrower path. The generated-media support reports redacted job metadata and artifact summaries through LemonMedia.MediaJobs; generated final-answer files that pass through the router auto-send path are recorded before channel dispatch. This is observability for generated media, not a stable provider-generation claim. Telegram and Discord /media status expose redacted job counts to channel operators without raw prompts, paths, bytes, captions, or provider responses. Lemon 1.0 does not claim OpenAI-compatible API server behavior, OpenAI-compatible Chat Completions/Responses API support, ACP editor integration, third-party frontend compatibility, autonomous persistent goal continuation loops, kanban dispatcher/worktree/UI parity, LSP semantic diagnostics, checkpointing for destructive shell commands, or multi-backend terminal parity unless a release note explicitly promotes a narrower path. The stable API surface is the documented Lemon control plane and first-party Web/TUI interfaces.

For web-tool bugs, include the prompt, tool name, target URL when shareable, interface, runtime mode, and whether the issue is plain text fetch/search or browser behavior. For browser bugs, include the browser.provider line from lemon doctor, whether Lemon runs from a release or a source checkout, the Chrome/Chromium executable used, and any screenshot artifact path under .lemon/browser-artifacts/.

Automation and Cron

Cron and scheduled automation are preview surfaces for stable 1.0. The supported boundary is operator-controlled scheduling through first-party control-plane/runtime paths, with reproducible failures covered as setup or runtime bugs.

Stable 1.0 does not support presenting cron as an unrestricted model-facing tool. Scheduled agent runs are expected to run in isolated forked sessions, carry their prior-run memory context, and block recursive cron management through model tool policy. Operator-controlled pause/resume/run-now/abort are supported first through the first-party runtime surfaces. Operator-controlled audit history is available through cron.audit and cron.audit WebSocket events. Treat advanced automation workflows, external scheduler integrations, and production SLA-style scheduling guarantees as post-1.0 work.

Telegram Rendering and Media

Telegram is supported as a remote chat interface for text-first agent runs. Stable 1.0 behavior includes:

• plain text delivery with Telegram entities for headings, bold, italic, inline code, fenced code blocks, links, lists, blockquotes, and simple markdown tables rendered as pipe-delimited text
• progress/status messages, cancellation controls, approval buttons, and concise run-failure messages
• /file put and /file get when Telegram file transfer is enabled
• document upload auto-save when enabled by config
• telegram_send_image for image files that already exist inside the active project or workspace roots
• optional generated-file auto-send, bounded by configured file count and size limits
• image batches through Telegram media groups when the Bot API accepts them, with sequential image/document fallback
• Discord finalized-run attachment delivery and optional generated-file auto-send, bounded by configured [gateway.discord.files] count and size limits

Not stable for 1.0:

• arbitrary rich media generation as a product feature
• image analysis as a Telegram interface feature
• provider-backed TTS or voice reply generation under production quota
• guarantees that every markdown extension renders visually identical to GitHub Markdown
• sending files from outside the active project or workspace roots

For Telegram or Discord media bugs, include the interface, command or tool used, file type, file size, relevant [gateway.telegram.files] or [gateway.discord.files] config, and whether the issue was manual file transfer, generated-file auto-send, or telegram_send_image.

The detailed support matrix lives in Release Checklist and Support Policy.

Not Supported for 1.0

These are outside the initial stable support boundary:

• native Windows installs outside WSL experimentation
• hosted Lemon service operation
• Discord behavior outside the text-first and file-delivery boundary, including voice, broad slash-command parity, and unproven DM workflows
• stable support guarantees for XMTP, SMS, voice, or other preview channel adapters unless explicitly promoted in release notes
• production-grade scheduling guarantees for cron or scheduled automation
• first-class browser automation as a stable support guarantee, generated media, image analysis, or TTS/voice behavior unless explicitly promoted in release notes
• OpenAI-compatible API server behavior, ACP editor integration, or drop-in support for third-party OpenAI-compatible frontends
• production support for third-party plugins or external plugin hosts
• Web/TUI/channel rollback controls or support guarantees beyond the preview checkpoint boundary. Preview checkpoints cover file-tool snapshots, configured risky-shell snapshots, redacted lifecycle events, redacted diagnostic metadata, Telegram/Discord redacted checkpoint status/events with lifecycle event counts/history, pushed active-run event notices, and diff/restore actions through /checkpoint plus the /rollback alias rollback command guidance/actions, and operator-only control-plane and TUI diff/restore methods. Chat checkpoint output does not expose raw file paths, file contents, raw session ids, or arbitrary file browsing.
• persistent /goal model-judging beyond the preview status/set/pause/resume/ continue/loop controls
• real multi-worker kanban execution beyond the deterministic bounded- concurrency/crash/reclaim dispatcher behavior
• stable Hermes-style LSP semantic diagnostics beyond the current preview checker/server/session status surface
• production-grade terminal container fleet parity beyond the current Docker/SSH preview boundary. The preview boundary includes local, local PTY, Docker, and SSH execution plus Docker hardening for read-only rootfs, no-exec /tmp, dropped capabilities, no-new-privileges, no-network default, and cgroup-observed CPU/memory/pids policy. Support bundles expose safe booleans and policy values only, without command text or output.
• provider routing, fallback providers, credential pools, and profile distribution parity
• production support for third-party plugins or unofficial MCP servers
• arbitrary local shell, provider, or OS customization issues
• old commits that are not the current stable release, preview build, or a requested diagnostic commit
• user-provided secrets, private prompts, memory contents, or tool outputs shared as part of an issue

Before Opening a Bug

Run:

lemon doctor

Doctor is offline unless you pass --live. Use lemon doctor --live --verbose for real, non-generating connectivity checks: the default provider's models list, Telegram getMe, and Discord /users/@me. Bot checks report the public username on success. OpenAI-compatible endpoints (including keyless local servers), Anthropic and Gemini are supported; OAuth-only/unsupported endpoints, channels without a probe, and missing credentials are explicitly skipped. Each request has a five-second timeout; concurrent live checks share a six-second overall deadline. Authentication, reachability, timeout and unexpected HTTP failures count as FAIL (exit 1). --json and support bundles include live results, but not tokens, raw provider bodies or endpoint URLs. A successful models-list request is not proof that a generation request will succeed.

By default --live checks only the default provider. To verify others, add --provider NAME for one named provider or --provider all for the default plus every configured provider (at most eight; the rest are reported as one skipped result). Each provider gets its own providers.live.<id> result using the same bounded models-list request, so one rejected key or unreachable endpoint does not hide the others. --provider requires --live; without it doctor stays offline.

For source-dev installs, generate a reviewed redacted bundle:

mix lemon.doctor --bundle

For release-runtime installs, generate:

lemon doctor --bundle

Review the zip before sharing it. The bundle is designed to exclude secrets and private data, but users remain responsible for checking attachments before posting them publicly.

The bundle manifest includes the Lemon app version, release name/version, release channel when available, source/release runtime mode, git commit/branch state, Elixir/OTP versions, OS, and CPU architecture.

For browser automation bugs, the bundle also includes browser_diagnostics.json with local driver lifecycle counters, the browser artifact directory, artifact count/byte totals, oldest/newest artifact timestamps, managed cleanup policy, and recent screenshot artifact metadata. It does not include screenshot bytes, page HTML, page text, cookies, private prompts, or tool outputs.

For generated-media bugs, the bundle includes media_diagnostics.json with the media job metadata directory, artifact directory, redacted job counts, type and status counts, artifact count/byte totals, cleanup policy, and recent job metadata. The bundle does not include prompts, raw artifact paths, generated bytes, provider responses, channel message bodies, or API credentials.

For provider setup bugs, the bundle includes provider_diagnostics.json with the default provider, default-model presence, configured provider count, credential-reference counts, ambient-provider presence booleans, routing fallback shape, credential-pool shape, and per-provider redacted configuration shape. It does not include API keys, secret names, raw base URLs, env var names, provider responses, or model prompts.

mix lemon.doctor also includes a providers.routing check. It reports when fallback routing is disabled, absent, configured without any credential-ready fallback, or able to rescue a not-ready default provider through a credential-ready fallback. The check only reports provider labels and counts; it does not expose key material, secret names, endpoint URLs, prompts, or provider responses.

For cron and scheduled-automation bugs, the bundle includes cron_diagnostics.json with job/run counts, enabled/disabled counts, active/failed run counts, status and trigger counts, next/last run timestamps, recent job shape, retry policy, recent run retry-lineage shape, lifecycle audit counts, audit action counts, and recent audit event shape. It hashes job/run ids, audit ids, agent ids, session keys, prompts, outputs, errors, schedules, names, memory-file paths, retry parent/root ids, and audit reasons; it records metadata keys and changed-field names only. It does not include raw prompts, outputs, errors, session ids, agent ids, memory paths, retry lineage ids, audit ids, audit reasons, or metadata values.

For Telegram and Discord setup bugs, the bundle includes channel_diagnostics.json with redacted transport enablement, credential-shape booleans, binding counts, file-transfer controls, generated-file auto-send shape, Telegram voice-transcription configuration, and Discord Message Content Intent declaration. It does not include bot tokens, secret names, raw chat IDs, raw channel IDs, raw guild IDs, or message bodies.

For extension/plugin setup bugs, the bundle includes extension_diagnostics.json with global, project, and configured extension directory existence, extension-file counts, extension-manifest valid/invalid counts, aggregate manifest capability/provider/host/distribution/audit shape, nested library-file counts, and file/path hashes. It does not load extension code and does not include raw source paths, file contents, manifest contents, distribution URLs, plugin names, provider names, or load-error messages.

Logs

By default, source-dev runs write logs to stdout/stderr. Increase verbosity with:

LEMON_LOG_LEVEL=debug ./bin/lemon

File logging is opt-in through ~/.lemon/config.toml:

[logging]
file = "~/.lemon/log/lemon.log"
level = "debug"

For release-runtime installs, stdout/stderr depends on how the runtime is started. CI release-smoke failures upload release logs from _build/prod/rel/<profile>/tmp/log/. When filing issues, include only relevant log excerpts and remove secrets, tokens, private prompts, memory contents, and tool outputs.

What to Include

Use the bug report template and include:

• install path: source-dev or release-runtime
• operating system and architecture
• Lemon commit, tag, or release artifact name
• interface: TUI, Web, Telegram, Discord, CLI, release runtime, or control plane
• command that failed
• expected behavior
• actual behavior
• relevant logs with secrets removed
• support bundle command output or attached reviewed bundle

Security Reports

Do not open public issues for suspected vulnerabilities or secret leaks. Use the security reporting path in the repository SECURITY.md and the safety guidance in Lemon Safety.

Useful Pages

Need	Page
Install path	Install Lemon
Full setup guide	Setup Guide
Run a local proof	Demo Lemon
Safety and redaction model	Safety
Release support matrix	Release Checklist
Product boundaries	Compare Lemon