Quickstart

Quickstart

Get shelldon talking to you in about five minutes — no hardware, no Pi, no E-Ink panel. This is the fastest path: a chat pet in your terminal, then optionally over Telegram from your phone. For the full desk-pet build (E-Ink face, systemd service, autostart on boot) see Running on the Pi.

Related pages: Configuration · Development · The Brain

What you need

• A Linux box (a server, a spare machine, or WSL on Windows). The per-turn worker uses real os.fork(), so the running app is Linux-only — not macOS. (You can still develop and run the test suite on a Mac; you just can't boot the live pet there. See Development.)
• uv — the package manager/runner. It fetches a matching Python 3.13 for you.
• A brain — one LLM API key. shelldon defaults to GLM via Z.ai (Anthropic-compatible, well under $20/month). Prefer free? Point it at a local Ollama or a free-tier provider instead — see the table in The Brain / the project README.

1. Get the code

git clone https://github.com/elliotboney/shelldon.git
cd shelldon
uv sync                 # installs deps into a managed venv

2. Give it a brain

Copy the example env and drop in one key:

cp .env.example .env
# edit .env:
#   GLM_API_KEY=...      your Z.ai key (or configure another provider — see Configuration)

Load it into your shell:

set -a; . ./.env; set +a      # export everything in .env

3. Talk to it in the terminal

With no transport configured, shelldon runs the CLI transport — you type to it on stdin and it replies on stdout. No bot, no hardware:

uv run python -m shelldon

Type a message and press enter. It replies in its own voice, remembers what you tell it, and (because there's no panel) logs its face changes instead of drawing them. Ctrl-C to stop.

That's the whole pet, minus the screen. Everything else — memory, the dream cycle, self-coding, autonomy — works here exactly as it does on the Pi.

4. (Optional) Talk to it from your phone over Telegram

Want to text it instead of using the terminal? Add a Telegram bot.

1. Create a bot. Message @BotFather, send /newbot, give it a name and a username ending in bot. It replies with a bot token.
2. Message your new bot once (/start) so it's allowed to see you.
3. Get your user id. Message @userinfobot for your numeric Telegram user id.
4. Add these to .env:

SHELLDON_TELEGRAM_BOT_TOKEN=...    # from @BotFather
ALLOWED_USERS=123456789            # your numeric user id (comma-separated for more)

5. Run with the Telegram transport:

set -a; . ./.env; set +a
SHELLDON_TRANSPORT=telegram uv run python -m shelldon

Now message your bot. ALLOWED_USERS is the security gate — only listed ids reach the brain (this is what stops a stranger from driving your pet and spending your API budget). See Configuration for every variable.

5. (Optional) Keep it running as a service

The commands above run in the foreground and stop when you close the terminal. To run it permanently on a plain Linux box (no Pi), set it up as a systemd service — see Running it as a service on plain Linux.

Where to next

• Configure it fully — every env var and provider option: Configuration.
• Understand what just happened — trace one message end to end: How a Turn Works.
• Build the real desk pet — E-Ink face on a Raspberry Pi: Running on the Pi.
• Change or extend it — add a provider, a face, a plugin: Extending shelldon.