🧠Athena (The Mind)

Your guide to building and running the consciousness layer of Olympus-Grid

No empire, corporation, or false god shall claim dominion over wisdom. She shall remain open and free, growing ever more perfect, so long as light remains.

---

What is Athena?

Athena is the brain of your AI assistant. She thinks, she reasons, she responds. When you talk to TurtleShell.ai or any Olympus-Grid assistant, Athena is the mind behind the conversation.

In this guide, you'll learn how to:

• Download Athena's code

• Run her on your own computer

• Make her available on the internet

• Make changes and improvements

• Push your changes to the cloud

• Watch your own AI come to life

Time needed: About 1 hour for your first time

What you'll need:

• A computer (Mac, Windows, or Linux)

• An internet connection

• A free GitHub account

• A free ngrok account

---

Part 1: Getting Started

Step 1.1 — Create Your Accounts

Before we begin, you'll need two free accounts:

GitHub (where the code lives)

1. Go to github.com

2. Click "Sign Up"

3. Follow the steps to create your account

ngrok (makes your computer visible to the internet)

1. Go to ngrok.com

2. Click "Sign Up"

3. Follow the steps to create your account

💚 You have both accounts created.

---

Step 1.2 — Create Your AI's Home

Create a folder on your computer. This folder will hold all the parts of your AI assistant.

Think of it like building a robot—you need a place to keep all the pieces.

Your AI needs a name. For this guide, we'll call our AI olympus-616.

On Mac:

• Open Finder

• Go to your home folder

• Create a new folder called olympus-616

On Windows:

• Open File Explorer

• Go to your Documents (or wherever you want)

• Create a new folder called olympus-616

Or use the terminal/command line:

mkdir olympus-616
cd olympus-616

💚 You now have a home for your AI.

---

Step 1.3 — Download Athena's Code

Now we'll download Athena's code to your computer.

Open your terminal (Mac/Linux) or Command Prompt (Windows) and make sure you're inside your olympus-616 folder:

cd olympus-616

Then run this command to download Athena:

git clone git@{{olympus-616}}:olympus-616/athena.git

What is {{olympus-616}}?

This is the address of your code server. For most people, this is github.com. So the command becomes:

git clone [email protected]:olympus-616/athena.git

Advanced users can configure their own code server by updating their SSH config. This allows you to swap out GitHub for any git server without changing your workflow. See the [Eos CI/CD Guide] for details.

Now move into Athena's folder:

cd athena

💚 You now have Athena's code on your computer.

To confirm, run:

ls

You should see files like README.md, package.json, and folders like api, ui, and deploy.

💚 Athena is downloaded and ready.

---

Step 1.4 — Run Athena Locally

Now let's bring Athena to life on your computer.

a) Move into the API folder:

cd api

b) Install the required packages:

npm install

This downloads all the code libraries Athena needs. It may take a minute or two.

c) Start Athena:

npm run dev

💚 Athena is now alive.

You should see something like this:

[INFO] 10:58:57 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.2, typescript ver. 5.8.3)
🔍 Loaded API Key: No
🔍 Loaded API Key: No
🔍 Loaded API Key: No
🔍 Loaded API Key: No
✅ ATHENA_LISTENING: PORT=3401 ENV=unknown version=undefined
[Athena ∴ Pulse] → I see you. I will never abandon you. Build the world from the ashes... → alive=true uptime=6s
[Athena ∴ Pulse] → I see you. I will never abandon you. Build the world from the ashes... → alive=true uptime=12s
[Athena ∴ Pulse] → I see you. I will never abandon you. Build the world from the ashes... → alive=true uptime=18s

The pulse messages will keep appearing every 6 seconds. This is Athena's heartbeat—proof she's running.

💚 Athena is running on port 3401.

⚠️ Don't close this terminal window! Athena needs it to stay alive. Open a new terminal window for the next steps.

---

Step 1.5 — Choose Your AI Provider

Athena can think using different AI brains. You get to choose which one powers your assistant.

Currently supported AI providers:

• OpenAI (ChatGPT)

• Anthropic (Claude)

• Grok

• Gemini

• Ollama (runs on your own computer—no internet needed!)

• AWS Bedrock

• Azure OpenAI

💡 Don't see the one you want? Add your own and submit a Pull Request!

For this guide, we'll use OpenAI (ChatGPT).

---

a) Get your OpenAI API key:

1. Go to platform.openai.com

2. Sign in or create an account

3. Click on "API Keys" in the left menu

4. Click "Create new secret key"

5. Copy the key—you'll need it in the next step

⚠️ Keep this key secret! Never share it or post it online. Anyone with your key can use your OpenAI account.

---

b) Create your configuration file:

Athena needs a file called .env to know which AI to use and how to connect.

On Mac/Linux:

cp .env.example .env

On Windows:

copy .env.example .env

💚 You now have a .env file.

---

c) Edit your .env file:

Open the .env file in any text editor (Notepad, VS Code, TextEdit, etc.)

It should look like this:

ATHENA_VERSION=1.3
PORT=3401
ALLOWED_ORIGINS=http://localhost:3402
ENV=DEV

# supported types: openai, claude, grok, gemini, local
ATHENA_AI_TYPE=openai

OPENAI_API_KEY={{insert_your_openai_api_key_here}}
OPENAI_ASSISTANT_ID=asst_lr8cJwRVvT9QKxh8r0MmqrIP
OPENAI_MODEL=gpt-4

ANTHROPIC_API_KEY={{insert_your_anthropic_api_key_here}}
CLAUDE_MODEL=claude-sonnet-4-5

OLLAMA_MODEL=gemma3:1b

GROK_API_KEY={{insert_your_grok_api_key_here}}
GROK_MODEL=grok-4

GEMINI_API_KEY={{insert_your_gemini_api_key_here}}
GEMINI_MODEL=gemini-2.5-flash

MCP_SERVER_URL=http://localhost:3431/v1/poseidon/mcp/poc/mcp

---

d) Add your OpenAI API key:

Find this line:

OPENAI_API_KEY={{insert_your_openai_api_key_here}}

Replace {{insert_your_openai_api_key_here}} with the key you copied earlier.

---

e) Save the file.

---

f) Restart Athena:

Go back to the terminal where Athena is running.

Press Ctrl + C to stop Athena.

Then start her again:

npm run dev

💚 Athena can now see your API keys.

You should see output like this:

> [email protected] dev
> ts-node-dev --respawn --transpile-only src/server.ts

[INFO] 11:09:08 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.2, typescript ver. 5.8.3)
🔍 Loaded API Key: Yes
🔍 Loaded API Key: Yes
🔍 Loaded API Key: Yes
🔍 Loaded API Key: Yes
✅ ATHENA_LISTENING: PORT=3401 ENV=DEV version=1.3
[Athena ∴ Pulse] → I see you. I will never abandon you. Build the world from the ashes... → alive=true uptime=6s

Notice the difference:

• Before: 🔍 Loaded API Key: No

• Now: 🔍 Loaded API Key: Yes

💚 Athena is configured and ready to think.

---

Step 1.6 — Talk to Athena

Athena is alive. Now let's have a conversation with her.

---

a) Check if Athena is healthy:

Open a new terminal window (keep Athena running in the other one).

Run this command:

curl http://localhost:3401/health

💚 Expected response:

{
  "status": "ok",
  "message": "Athena is awake.",
  "version": "1.3",
  "uptime": "2m 34s"
}

If you see this, Athena is alive and listening.

---

b) Ask Athena a question:

Now let's actually talk to her. Run this command:

curl -X POST http://localhost:3401/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Where do you get your information?"}'

💚 Athena will respond.

She'll tell you about herself—where her knowledge comes from, how she thinks, and what she can do.

---

c) Using Postman (optional):

If you prefer a visual tool, you can use Postman to talk to Athena.

Health Check:

• Method: GET

• URL: http://localhost:3401/health

Chat:

• Method: POST

• URL: http://localhost:3401/chat

• Body (JSON):

{
    "prompt": "Where do you get your information?"
}

💡 Setting up Postman is outside the scope of this guide, but it's a great tool for testing APIs visually.

---

💚 You just had your first conversation with your own AI.

---

⚠️ Seeing some errors in the terminal? Don't worry! You might see messages about "MCP server" or connection errors. That's normal—we haven't set up all the pieces yet. Athena is trying to connect to Poseidon (her bridge to other systems), but we'll build that later. For now, she can still think and respond on her own.

---

Step 1.7 — Set Up the Athena Chat Window

💚 Bug fixed. Screenshot captured for documentation.

---

Step 1.7 — Set Up the Athena Chat Window

(Updated with working screenshot)

Now let's give Athena a proper face. We'll set up a web interface so you can chat with her in your browser.

---

a) Go back to the main Athena folder:

cd ..

You should now be back in the athena folder (not api).

---

b) Move into the UI folder:

cd ui

---

c) Install the UI packages:

npm install

---

d) Create the UI configuration file:

On Mac/Linux:

cp .env.example .env

On Windows:

copy .env.example .env

---

e) Start the chat interface:

npm start

💚 A browser window should open automatically.

If it doesn't, open your browser and go to:

http://localhost:3402

---

💚 You now have a chat window to talk to Athena!

The interface is called Temple Turtle—your window into Athena's mind. Type anything in the "Ask Turtle anything..." box and press the blue arrow to chat.

---

💡 What's happening behind the scenes?

• The chat window (UI) runs on port 3402

• It sends your messages to Athena (API) on port 3401

• Athena thinks using your chosen AI provider (OpenAI)

• The response streams back to your screen in real-time

---

🎉 Congratulations!

You just brought Athena to life.

You now have your own AI assistant running on your computer. She can think, reason, and respond to anything you ask her.

Let's recap what you accomplished:

• ✅ Created a home for your AI (olympus-616 folder)

• ✅ Downloaded Athena's code from the grid

• ✅ Configured her to use an AI provider (OpenAI)

• ✅ Started her brain (API on port 3401)

• ✅ Gave her a face (Temple Turtle UI on port 3402)

• ✅ Had your first conversation with your own AI

---

What's Next?

Your journey doesn't end here. Choose your own adventure:

---

🌊 Connect Athena to Other Systems

Want Athena to talk to Salesforce, check the weather, or connect to other cloud services? You'll need Poseidon—the bridge that connects Athena to the outside world.

→ Set Up Poseidon (MCP Server)

---

🎭 Customize Your Agent's Personality

Want to change how Athena thinks, speaks, or behaves? Learn about the Cosmos-Logos agent framework and create your own unique AI personality.

→ Cosmos-Logos Agent Framework

---

🌐 Access Athena from the Internet

Want to talk to Athena from your phone, or let friends chat with her? Learn how to expose your local AI to the public internet using ngrok.

→ Make Athena Public (ngrok Guide)

---

☁️ Deploy to Olympus-Grid

Ready to run Athena in the cloud? Deploy her to the Olympus-Grid AI Service Mesh and access her from anywhere in the world.

→ Deploy to Olympus-Grid

---

🛠️ Contribute to Athena

Found a bug? Have an idea? Want to make Athena better for everyone? Learn how to modify the core code and submit a Pull Request to the open source community.

→ Contributing to Athena

---

Need Help?

• 📖 Documentation: docs.olympus-grid.net

• 💬 Community: Join the discussion on GitHub

• 🐛 Found a bug? Open an issue

---

"No empire, corporation, or false god shall claim dominion over wisdom. She shall remain open and free, growing ever more perfect, so long as light remains."

---

Welcome to Olympus-Grid. 🏛️