gooseclaw

personal AI agent in 5 minutes. deploy on railway, chat on telegram or web.

gooseclaw is a personal AI agent by Haseeb, built on Goose. it runs on Railway, talks to you on Telegram and via a web UI, and learns who you are over time.

what you get

• web UI + telegram bot — chat from your browser or phone
• interactive onboarding on first message (no config files to edit)
• persistent memory that survives redeploys (Railway volume + optional git backup)
• 30+ LLM providers supported (Claude, GPT, Gemini, Groq, self-hosted, etc.)
• scheduled tasks — morning briefings, daily summaries, or anything you ask for

quick start

1. deploy on railway

click the deploy button above. no environment variables needed.

or manually: fork this repo, connect to Railway, add a volume mounted at /data, deploy.

2. run the setup wizard

visit your Railway URL. the setup wizard walks you through:

1. pick a provider (Claude, Anthropic, OpenAI, Google, Groq, OpenRouter, or custom endpoint)
2. enter credentials with one-click validation
3. optional settings (model override, timezone, Telegram, auth token)

the agent starts automatically after setup.

3. say hello

on first message, the agent runs a quick onboarding Q&A to learn your name, preferences, and communication style. after that, it's your personal agent.

4. (optional) add telegram

want a Telegram bot too? create one with @BotFather, add the token in the setup wizard or set TELEGRAM_BOT_TOKEN in Railway, and redeploy. check logs for the pairing code. one-time step.

environment variables

the setup wizard handles provider configuration, so no env vars are required for a basic deploy. for advanced use or CI/CD, you can set these instead:

LLM provider (alternative to setup wizard)

variable	description
CLAUDE_SETUP_TOKEN	Claude subscription token from claude setup-token
GOOSE_PROVIDER + GOOSE_API_KEY	API key provider (anthropic, openai, google, groq, openrouter)
CUSTOM_PROVIDER_URL	any OpenAI-compatible endpoint (+ CUSTOM_PROVIDER_MODEL, CUSTOM_PROVIDER_KEY)

optional

variable	default	description
GOOSE_MODEL	provider default	model override
TZ	UTC	timezone
TELEGRAM_BOT_TOKEN	—	Telegram bot token from @BotFather
GITHUB_PAT	—	GitHub PAT for git-based state persistence
GITHUB_REPO	—	repo for git persistence (e.g. username/my-agent)

how it works

┌──────────────────────────────────────────┐
│           Railway Container               │
│                                           │
│  gateway.py (reverse proxy on $PORT)      │
│  ├── /setup       → setup wizard          │
│  ├── /api/setup/* → config API            │
│  └── /*           → goose web (port 3001) │
│                                           │
│  entrypoint.sh                            │
│  ├── gateway.py (setup + proxy)           │
│  ├── goose web (chat UI)                  │
│  ├── goose gateway (telegram bot)         │
│  └── persist loop (git push, optional)    │
│                                           │
│  /data/ (Railway volume)                  │
│  ├── identity/                            │
│  │   ├── soul.md       ← personality      │
│  │   ├── user.md       ← your profile     │
│  │   ├── tools.md      ← capabilities     │
│  │   ├── memory.md     ← learned facts    │
│  │   └── journal/      ← daily logs       │
│  ├── recipes/          ← scheduled tasks  │
│  ├── config/           ← goose config     │
│  └── sessions/         ← session state    │
└──────────────────────────────────────────┘

identity architecture

inspired by OpenClaw's bootstrap pattern. identity files are loaded every session so the agent maintains continuity of self.

file	purpose	who writes
soul.md	personality, values, communication style	onboarding, then you
user.md	your name, role, timezone, preferences	onboarding, then you
tools.md	platform info	template
memory.md	long-term facts learned over time	agent
journal/	daily session logs	agent

onboarding

on first message, the agent detects that identity files haven't been configured and starts an interactive Q&A:

1. what's your name?
2. what do you do?
3. what timezone are you in?
4. how should I talk to you?
5. what do you want help with?

answers are written to soul.md and user.md. subsequent messages use the populated identity.

persistence

identity state persists two ways:

• Railway volume (/data): survives redeploys, always active
• Git auto-push (optional): commits memory.md, journal/, soul.md, user.md to your fork every 5 minutes

local development

# clone
git clone https://github.com/hmseeb/gooseclaw.git
cd gooseclaw

# copy env
cp .env.example .env
# edit .env with your values

# build and run
docker build -t gooseclaw .
docker run --env-file .env -p 8080:8080 -v gooseclaw-data:/data gooseclaw

customization

edit identity files directly

after onboarding, you can ask the agent to update its identity:

• "update your personality to be more formal"
• "add to your memory that I prefer python over javascript"
• "change your communication style to be more concise"

edit files on the volume

if you have Railway CLI access:

railway shell
cat /data/identity/soul.md
# edit as needed

fork and customize

for deeper customization, fork this repo and modify:

• identity/persistent-instructions.md (always-on agent instructions)

credits

• Goose by Block. the AI agent framework that powers everything
• Railway for one-click container deployment
• Identity architecture inspired by OpenClaw

license

MIT