lobsterx 0.2.0b0

Background AI assistant working as a Telegram bot, built specifically for document-related use cases

LobsterX🦞

LobsterX is an AI agent inspired by OpenClaw (formerly known as MoltBot or ClawdBot), which focuses on document-related tasks.

It runs as a Telegram bot as comes with a CLI interface to set up the necessary environment variables.

Prerequisites

• Python (if setting up the bot natively, preferably with uv) or Docker (if deploying with Docker)
• A Telegram Bot Token, in order to connect to Telegram. Follow this guide on how to create your Telegram bot with BotFather.
• A LlamaCloud API key, in order to give LobsterX document-processing capabilities. Sign up on LlamaCloud here.
• An API key for Google, OpenAI or Anthropic (you can choose one among the three or swap between different providers)

Installation

Install the bot natively:

# uv (recommended)
uv tool install lobsterx --prerelease=allow
# pip
pip install lobsterx

Pull the docker image (only works for AMD64-compatible platforms):

docker pull ghcr.io/astrabert/lobsterx:main

Setup

Through environment variables, you can customize the setup of LobsterX:

• LOBSTERX_LLM_PROVIDER: LLM provider (choose between google, anthropic and openai). Default is openai
• LOBSTERX_LLM_MODEL: LLM model (choose among available models). Default is gpt-4.1

You then need to set three required env variables:

• LOBSTERX_LLM_API_KEY: API key for the LLM (you can also use OPENAI_API_KEY, GOOGLE_API_KEY or ANTHROPIC_API_KEY, depending on the provider).
• TELEGRAM_BOT_TOKEN: token for the Telegram bot
• LLAMA_CLOUD_API_KEY: API key for LlamaCloud

You can use the setup wizard to configure LobsterX interactively on the terminal:

lobsterx setup --interactive

Or pass options from CLI:

lobsterx setup --provider google \
    --model gemini-3-flash-preview \
    --api-key $GOOGLE_API_KEY \
    --llama-cloud-key $LLAMA_CLOUD_API_KEY \
    --telegram-token $TELEGRAM_BOT_TOKEN

This will create a .env file with the necessary variables, which will be loaded by LobsterX at runtime (make sure not to share it with anyone).

If you wish to further customize the instructions that LobsterX has access to, you can use an AGENTS.md file, saved under the same directory where the agent process is running.

Run

Run LobsterX as a CLI app:

lobsterx run 

You can set the --log-level option, if you wish to have more or less logging.

Run LobsterX in a Docker container referencing a .env file:

docker run ghcr.io/astrabert/lobsterx:main --env-file=".env"

Or, setting env varaibles directly (not recommended):

docker run ghcr.io/astrabert/lobsterx:main \
    --env="LOBSTERX_LLM_PROVIDER=openai" \
    --env="LOBSTERX_LLM_MODEL=gpt-4.1"\
    --env="LOBSTERX_LLM_API_KEY=sk-xxx" \
    --env="LLAMA_CLOUD_API_KEY=llx-xxx" \
    --env="TELEGRAM_BOT_TOKEN=tok-xxx"

Use as a Telegram Bot

When on Telegram, you can perform two actions:

• Sending PDF files, which will be downloaded by the bot
• Sending text messages, which will work as prompts for the bot to start a new task

With /start command, you will have a welcome message explaining how to use the bot

How LobsterX Works

LobsterX is a generalist AI agent based on three main principles:

• LlamaIndex Agent Workflows: a powerful workflow engine that allows event-driven, stepwise execution of specific tasks and functions. LobsterX uses a cyclic workflow to go through thinking, tool-calling and observing repeatedly until it produces its final output.
• Structured outputs: the LLM underlying the agent is forced to produce JSON outputs that comply with certain schemas (a tool call, a thought, an observation...): outputs are produced informed by the previous chat history, and based on context about available tools and specific tasks the agent has to perform.
• Security by design: the agent does not have access to your real filesystem, but it does have access to a virtualized copy of it provided through AgentFS. PDFs sent over Telegram are also not downloaded into your real filesystem, but written within AgentFS. Files such as .envs or other popular credential files (.npmrc, .pypirc, .netrc) are excluded from the virtual filesystem, and thus unaccessible to the agent. The agent cannot use bash commands (it has access to filesystem-based tools like read/write/edit/grep/glob for AgentFS) to avoid it being able to perform destructive or vulnerable operations.

Here is what happens when you send a prompt to LobsterX:

Along with the final response, the agent will also send you a report of everything it did during its session as a markdown file (namedd session-<random-id>-report.md).

License

This package is provided under MIT License

Contributing

For contributions, refer to the contributing guide