Setup.

From zero to a running agent. One command if you're ready, or step-by-step below.

Node.js 20+ Anthropic API key macOS or Linux Telegram account
⚡

One-Command Install.

Have Node.js, an Anthropic API key, and a Telegram account? Run this:

Terminal
$ curl -fsSL https://ghostclaw.io/install.sh | bash

The installer walks you through everything — API key, Telegram bot creation, personality, auto-start. Done in 5 minutes.

Prefer to do it manually? Follow the steps below.

1

Get Node.js & Git.

First, open a terminal. On Mac: press Cmd + Space, type "Terminal", hit enter. On Linux: Ctrl + Alt + T.

Then check if you already have what you need:

Terminal
$ node --version
$ git --version

If both print a version number, you're good — skip to step 2.

Missing Node.js? Download the LTS version from nodejs.org, run the installer, then restart Terminal. You need v20 or higher.

Missing Git? On Mac, just run git --version — it'll prompt you to install it automatically. On Linux: sudo apt install git (Ubuntu/Debian) or sudo dnf install git (Fedora).

2

Install Claude Code.

Claude Code is the CLI that runs the agent. One command:

Terminal
$ npm install -g @anthropic-ai/claude-code
Before this step — get an API key

GhostClaw runs on the Anthropic API — you need an account and a key. Go to console.anthropic.com, create an account, add a card, and create an API key. It's pay-as-you-go: most people spend $5–20/month at normal usage. There's no free tier, but costs are predictable — a typical conversation costs a few cents. Once you have the key, the installer will ask for it and store it for you.

3

Get a Telegram Bot.

You need a bot token before setup. Open Telegram and message @BotFather:

Telegram — @BotFather
> /newbot
# follow the prompts, pick a name and username
# BotFather gives you a token like:
# 1234567890:ABCdef...
# copy that, you'll need it in a moment
Tip

Give the bot a username ending in bot — that's Telegram's requirement. Something like myghost_bot or workagent_bot.

4

Clone and Run.

Clone the repo, install dependencies, and hand it to Claude. It reads the setup instructions automatically.

Terminal
$ git clone https://github.com/b1rdmania/ghostclaw.git
$ cd ghostclaw
$ npm install
$ claude

Claude reads the project and knows what to do. It'll run /setup-ghostclaw and ask you a series of questions — your bot token, your Telegram user ID, your timezone, personality preferences. Just answer them.

5

Start the Agent.

Once setup is done, start GhostClaw:

Terminal
$ npm start

Then open Telegram, find your bot, and say hello. GhostClaw also has a web dashboard — open localhost:3333 in your browser (that means: open Chrome/Safari and type that into the address bar). It shows live status, message history, and running tasks.

Keep it running

GhostClaw needs to stay running to respond. The installer can set up launchd (macOS) or systemd (Linux) to auto-start on boot. On your daily driver, just leave the terminal open.

it's awake now.

Optional Extras

Not required. But useful if you want to deploy things or manage code from the agent.

GitHub CLI

Lets GhostClaw open PRs, manage issues, and interact with repos on your behalf.

cli.github.com →

Vercel CLI

Lets GhostClaw deploy sites directly. Needed for the brand-audit skill and frontend deploy workflows.

vercel.com/docs/cli →

Perplexity API Key

Powers the web research skill. Without it, web search falls back to a slower path. Worth having.

perplexity.ai/settings/api →

ElevenLabs API Key

Required for voice transcription and voice reply add-ons. Not needed for text-only setups.

elevenlabs.io →

Common Questions

Do I need a dedicated machine?

No, but it helps. GhostClaw runs fine on your daily driver — just leave the terminal open. For always-on operation, a Mac Mini, old laptop, or cheap VPS (4GB RAM is plenty) works well.

What does "bare metal" actually mean?

No Docker, no containers, no cloud functions. It's a single Node.js process running directly on your machine with full filesystem access. That's intentional — it's faster, simpler, and you know exactly what it can touch.

Can I run it on Windows?

macOS and Linux are officially supported. Windows via WSL2 works for most people but isn't tested. If you hit issues, the community can usually help.

How do I update GhostClaw?

Pull from GitHub and restart. If you have the /add-update-check skill installed, it'll notify you on Telegram when there's a new release.

Terminal — inside ghostclaw/
$ git pull
$ npm install
$ npm start

Something broke. Where do I get help?

Open a GitHub issue with what you ran, what you expected, and what happened. Or join the Telegram community — someone's usually around.