Skip to content

FAQ

What is g-agent for?

g-agent is a self-hosted runtime for agentic digital identity.

It is for building digital characters from a life, a mission, a relationship, an imagined person, or a version of yourself. The character can remember context, live in your channels, use tools, and show up visually through selfie or mirror-photo generation.

Common uses:

  • agentic yourself: a digital identity that carries your values, memory, voice, and working style
  • digital legacy: a preserved self, mission, relationship, or worldview that keeps continuity over time
  • personal operators for inbox, calendar, files, and workflow automation
  • agentic girlfriend or companion characters with long-term memory and consistent style
  • characters that can live in WhatsApp, Telegram, Discord, Email, and CLI
  • controlled tool execution under local policies

Which channels are supported?

  • CLI
  • Telegram
  • WhatsApp
  • Discord
  • Email (IMAP/SMTP with consent gate)
  • Slack (Socket Mode)

Slack is available through Socket Mode. Other channels should be treated as plugins or future hardening work.

Can I use local model endpoints (OpenAI-compatible proxy)?

Yes. Set routing.proxy_provider to "proxy" and configure providers.proxy with your endpoint's apiBase + apiKey in ~/.g-agent/config.json. This works with CLIProxyAPI, vLLM, LiteLLM, or any OpenAI-compatible endpoint. See Configuration for examples.

Note: The provider registry does not interfere with proxy mode. Custom model names pass through without modification.

Which LLM providers are supported out of the box?

Anthropic, OpenAI, Gemini, DeepSeek, Groq, Zhipu, Moonshot, DashScope, OpenRouter, AiHubMix, and Ollama. Provider-specific logic (env vars, model prefixes, parameter overrides) is handled automatically by the declarative provider registry.

What is the provider registry?

A declarative system that replaces hardcoded if-elif chains for provider configuration. It auto-detects providers from model names, sets environment variables, applies correct LiteLLM prefixes, and handles model-specific parameter overrides. See Configuration → Provider registry.

Does memory persist across sessions?

Yes. Memory is persisted under your profile workspace (for example ~/.g-agent/workspace/memory/).

The goal is not only chat history. Memory is the continuity layer for identity, preferences, relationships, projects, lessons, and the parts of a character that should not reset.

Can g-agent send proactive reminders/tasks?

Yes. It supports cron/scheduled workflows and proactive message jobs.

Can I still run this privately for personal use?

Yes. The runtime remains local-first with profile and policy controls.

How do I keep it secure by default?

Minimum baseline:

  • keep tools.restrictToWorkspace: true
  • keep strict allowFrom lists per channel
  • use separate data profiles for personal vs guest workloads
  • scope integration credentials to least privilege
  • for Email: ensure consent_granted is only true when you explicitly approve mailbox access

Can I isolate guest users from personal data?

Yes. Use separate profiles (G_AGENT_DATA_DIR) and limited policy presets.

How do I debug runtime issues quickly?

Use:

  • g-agent status
  • g-agent doctor --network
  • journalctl --user -u g-agent-gateway.service -u g-agent-wa-bridge.service -n 120 --no-pager

Does g-agent onboard overwrite my config?

No. If a config already exists, onboard deep-merges new defaults while preserving your existing values (API keys, allowlists, customizations). It is safe to re-run after upgrades.

How do I reset my conversation history?

Use g-agent new to archive and clear sessions:

  • g-agent new — clears the default CLI session (archived to ~/.g-agent/sessions/archive/)
  • g-agent new --all --yes — clears all sessions
  • g-agent new --channel whatsapp — clears WhatsApp sessions only
  • g-agent new --no-archive — deletes without archiving

How do I secure the WhatsApp bridge?

Set channels.whatsapp.bridgeToken in your config to a shared secret. The bridge will require authentication before accepting commands. Without a token, any process on localhost can connect to the bridge WebSocket.

Where should I start contributing?

Read:

  1. Contributing
  2. Security
  3. Configuration