Set up Charles

Get Charles running 24/7 on your own server in about 30 minutes — most of it waiting for installs. Then, optionally, add Claude Code so you can change the bot by describing what you want.

Before you start

You need three free accounts (plus Telegram if you want phone alerts). Keep the keys somewhere safe — you'll paste them in step 4.

Server setup

1Create a server

In DigitalOcean: Create → Droplets, then choose:

Click Create Droplet and copy its IPv4 address once it's ready — below it's called YOUR_SERVER_IP.

2Connect to it

Open PowerShell (Windows) or Terminal (Mac/Linux) and log in. Type yes the first time, then your password.

ssh root@YOUR_SERVER_IP

Your prompt changes to something like root@charles:~# — every command from here runs on the server.

3Run the installer

One command sets up everything: Python 3.11, the Charles code from GitHub, all packages, swap space, the firewall, auto-start services, the monthly rule check and the charles-* commands. It takes 5–10 minutes and is safe to run again (re-run it to update an older install).

curl -fsSL https://charles-bot.xyz/install.sh -o install.sh
bash install.sh

Prefer to read it first? View install.sh — it's plain bash.

4Add your keys

Open the keys file the installer created:

nano ~/charles/.env

Replace the placeholder values with your keys (leave the Telegram lines as they are if you're skipping it). Other lines in the file can stay as they are.

ALPACA_API_KEY=your_paper_key
ALPACA_SECRET_KEY=your_paper_secret
GROQ_API_KEY=your_groq_key
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Save with Ctrl+X, then Y, then Enter. To change a key later, run charles-keys: it saves the new key and restarts the bot.

5Start Charles

charles-start

1. Open the dashboard at http://YOUR_SERVER_IP:8502. Bookmark it — it works on your phone too.
2. Watch it come up with charles-logs (press Ctrl+C to stop watching). Look for ✅ Alpaca connected and ✅ Groq connected. The first start can take a few minutes.

That's it. Charles now trades during market hours, restarts itself after a crash or reboot, and alerts you on Telegram.

Everyday commands

Run these on the server after logging in with ssh.

Change the bot with Claude Code

Claude Code is Anthropic's AI coding assistant for the terminal. Installed on the same server, it can read Charles's code, logs and data, explain what the bot did, and make the changes you ask for — then restart the bot and check it came back healthy. You describe the change; it does the editing.

1Install and sign in

curl -fsSL https://claude.ai/install.sh | bash
exec bash   # reload the shell so the claude command is found

Start it inside tmux, so the session keeps running if your connection drops:

tmux new -s claude
cd ~/charles
claude

The first time, Claude Code asks you to sign in. The server has no browser, so it shows a link: open it on your own computer, sign in, and paste the code it gives you back into the terminal.

To leave Claude running and log out, press Ctrl+B then D. Next time, ssh in and run tmux attach -t claude to pick up where you left off.

2Your first session

1. Type /init. Claude reads the project and writes a CLAUDE.md file describing it — that file is loaded at the start of every session, so Claude always knows how Charles is laid out.
2. Add your own house rules to CLAUDE.md (or just ask Claude to add them). For example:

   # My rules
   - Paper trading only. Never switch to live keys.
   - Never print or edit .env.
   - Commit every change with git, one change per commit.
   - After changing code, run charles-restart and check charles-logs for errors.

3. Make a branch for your own changes, so charles-update never tangles with them: ask Claude to "create a git branch called my-changes", or run git checkout -b my-changes.

3What to ask

Plain English works. A few ideas:

4Working safely

• Claude asks before it acts. It shows each file edit and command and waits for your yes. Once you trust a routine command (say charles-restart), choose "don't ask again" or use /permissions.
• Keep git as your undo button. Ask Claude to commit after every change. "Undo the last change" or git revert HEAD takes it back.
• Never paste API keys into the chat. Edit .env yourself with nano.
• Stay on paper while experimenting. A change that looks right can still trade badly — let it run on paper first.
• About root: on a fresh droplet you work as root. Claude Code runs fine that way with its normal approval prompts. Its "skip all permissions" mode is deliberately blocked for root — keep the prompts on.

Run on your own computer

Handy for a first look. You need Python 3.11 and git.

git clone https://github.com/nswansonprojects/charles.git
cd charles
python -m venv .venv
# Windows: .venv\Scripts\activate    Mac/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # then add your keys to .env
python main.py           # the bot
python webdash.py        # the dashboard, in a second terminal

The dashboard is at http://localhost:8502. Charles stops when your computer sleeps or shuts down.

Troubleshooting