.opengoat Folder Structure When This Section Is Complete

These folders are built step by step across Sections 1–8. Don't worry if it looks empty now — each section adds the files you need.

📁 .opengoat Full Folder Structure

$env:USERPROFILE\.opengoat\          ← BALIA OS home directory
├── identity\                         ← Created in Section 2
│   └── team_design.md               ← Team design document
├── .env                              ← Created in Section 3 (API keys & webhooks)
├── workspaces\                       ← Created in Section 3
│   ├── [agentid]\                    ← Created per agent in Section 4
│   │   ├── SOUL.md
│   │   ├── AGENTS.md
│   │   ├── IDENTITY.md
│   │   ├── HEARTBEAT.md
│   │   ├── TOOLS.md
│   │   ├── USER.md
│   │   └── SPEC_[name].md
│   └── security-guardian\            ← Auto-deployed in Section 3
├── agents\                           ← OpenClaw config files auto-generated in Section 5
│   └── [agentid]
│       ├── config.json
│       └── models.json
├── memory\                           ← Created in Section 6
│   └── _SKILL_STATUS.md             ← Cassette ON/OFF list (single source of truth)
└── skills\                           ← Cassettes added in Section 6
    └── [cassette-name]\
        └── SKILL.md

This folder is BALIA OS's home. All agent identities, memory, and skills are stored here.

---

💡 What is an API? — And why do you need one?

Think of your AI agents as employees who need to think before they act.

Every time an agent analyzes a situation, writes a report, or makes a decision, it needs to call an AI model to do that thinking. The API is the channel that makes that call — and the fuel that powers it.

Chat AI vs API — two different things:

	Chat AI	API
What it is	Your personal concierge	Your agents' thinking engine
Who uses it	You, directly	Your agents, automatically
Cost model	Subscription (flat rate)	Pay per use (input + output tokens)
Recommended	Paid plan — better reasoning	Start with $5 credit

Why run both? (Hybrid setup)

API billing works on input + output tokens — every word sent to the agent and every word it responds with costs a small amount.

This means how you instruct your agents matters.

Use your chat AI (paid plan recommended for better reasoning) to:

• Draft clear, concise instructions before sending to agents
• Summarize long documents before passing them to agents
• Pre-structure tasks so agents don't waste tokens figuring out what you want

A well-structured 200-token instruction costs a fraction of a vague 2,000-token back-and-forth. Your Chat AI is the strategist. Your agents are the executors. This combination keeps API costs low while keeping output quality high.

Before You Start — API Cost Transparency

BALIA OS requires an AI API key to run your agents. This is separate from the $48 guide cost.

What you need:

• An Anthropic account with at least $5 in prepaid credits
• All agents in this guide use Claude Sonnet 5

Why $5 is enough to start: Claude Sonnet 5 is priced at $2 per million input tokens and $10 per million output tokens (introductory pricing through August 31, 2026; pricing reverts to $3 input / $15 output after that date). A typical agent session uses a few thousand tokens. $5 gets you dozens of sessions to learn and experiment before spending more.

There is no free tier for the Anthropic API. A credit card is required. Add credits at: console.anthropic.com → Billing → Add credits (minimum $5)

This is the only external cost required to run BALIA OS. To put it in perspective: hiring a human assistant costs $2,000–$5,000 per month. Your AI team runs on $5 worth of API credits to get started. Same work. A fraction of the cost.

---

What You're Installing

By the end of this section you'll have five things ready:

• VS Code — your workspace for editing agent files and running commands
• Claude Code — the execution side of the hybrid setup from Section 1, automating error fixes and file edits inside VS Code. No extra purchase needed if you're already on Claude Pro
• Node.js — required to run OpenClaw and Claude Code
• OpenClaw — the AI agent framework that powers BALIA OS
• Anthropic API key — the AI engine your agents use to think
• Security Guardian — your automated setup assistant that manages files and verifies your configuration

How this section works: Copy the prompt below and paste it into your chat AI. The AI will guide you through the entire installation — asking your operating system, walking you through each step, and helping you fix anything that goes wrong. If you get stuck at any point, just describe the problem to the AI and it will help you through it.

---

▶ Paste this into your AI to get started

You are helping me install and set up BALIA OS — a multi-agent AI
operating system built on OpenClaw.

Your job is to guide me through the installation step by step.
Ask me one question at a time. Wait for my answer before moving on.
If I hit an error, help me fix it before continuing.

Here is everything we need to install and set up, in order:

STEP 1 — Check my operating system
Ask me: "Are you on Windows or Mac?"
Then give me the correct instructions for my OS throughout all steps.

STEP 2 — Install VS Code
Guide me to install VS Code from code.visualstudio.com
- Windows: download and run the installer. Make sure "Add to PATH" is checked.
- Mac: download, unzip, drag to Applications, then run the shell command
  to add "code" to PATH: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"
After install, ask me to open a terminal in VS Code and run:
  code --version
Ask me what it shows. If there's an error, help me fix it.

STEP 2b — Change the VS Code display language (optional)
VS Code defaults to English, so if English works for you there's
nothing to change here — tell me it's fine to skip this step entirely
and move straight to STEP 3.
If I want a different display language, guide me to:
1. Open the Extensions panel (Ctrl+Shift+X, or Cmd+Shift+X on Mac)
2. Search for the language pack I want (e.g. "Japanese Language Pack"
   by Microsoft) and install it
3. Click "Change Language and Restart" when it appears (or
   Ctrl+Shift+P → "Configure Display Language" if it doesn't)
4. Confirm VS Code restarts with the new language

STEP 3 — Install Python
In the VS Code terminal, ask the user to run:
  python --version
If "Python 3.x.x" appears, Python is already installed. Proceed to the next STEP.

If not, tell them to install from https://www.python.org/downloads/
- Windows: Run the installer. Make sure to check "Add Python to PATH".
- Mac: Run the installer and proceed through the defaults.

After installing, restart VS Code and run python --version again to confirm.

STEP 4 — Install Node.js
Guide me to install Node.js 22 or higher from nodejs.org (LTS version).
After install, ask me to run: node --version
Ask me what it shows.
- If v22 or higher: great, move on.
- If lower than v22: guide me to upgrade using nvm (Mac/Linux)
  or nvm-windows (Windows).
- If error: help me troubleshoot.

STEP 4b — Install Git
In the VS Code terminal, ask me to run:
  git --version
If a version number appears, Git is already installed. Proceed to the next STEP.

If not, tell me to install it:
- Windows: download and run the installer from git-scm.com/downloads —
  accept the defaults throughout.
- Mac: running git --version for the first time usually prompts you to
  install the Xcode Command Line Tools — accept and wait for it to finish.

After installing, restart the terminal and run git --version again to
confirm. You'll need this later, in Section 7, to back up your .opengoat
folder to a private GitHub repository.

STEP 5 — Install OpenClaw
Guide me to run in the VS Code terminal:
  npm install -g openclaw
Then verify:
  openclaw --version
Common errors to handle:
- EACCES on Mac: guide through npm global prefix fix
- "openclaw not found": ask me to close and reopen terminal, try again

STEP 5b — Install Claude Code
Explain this first:
"Claude Code is the execution side of the hybrid setup from Section 1.
It reads errors right there in VS Code and handles the file fixes and
command runs for you.
If you're already on a Claude Pro plan or higher ($20/mo+), no extra
purchase is needed — the claude.ai chat and Claude Code share the same
subscription and the same usage allowance.
If you picked Claude Pro as your chat AI back in Section 1, you can log
in with that same account here.
If your chat AI is something other than Claude (ChatGPT, Gemini, etc.),
you'll need a separate Claude Pro (or higher) plan, or Anthropic API
access, to use Claude Code."

Then guide me to:
1. In the VS Code terminal, install the CLI:
     npm install -g @anthropic-ai/claude-code
2. Verify the install:
     claude --version
   Confirm a version number appears.
3. In the VS Code Extensions panel (Ctrl+Shift+X), search for "Claude
   Code" (publisher: Anthropic) and install it.
4. In the VS Code terminal, run the following to log in for the first
   time:
     claude
   A browser window opens — guide me to log in with my Claude Pro
   account (or API key).
5. After logging in, confirm the terminal returns to a prompt.

Common errors to handle:
- EACCES on npm install (permission error, Mac/Linux): guide me to run,
  in order:
    mkdir -p ~/.npm-global
    npm config set prefix ~/.npm-global
    export PATH=~/.npm-global/bin:$PATH
  then retry.
- "claude: command not found": ask me to close and reopen the terminal,
  then try again.
- Login screen doesn't open: ask me to confirm I have a valid
  subscription or API access at console.anthropic.com.

STEP 6 — Get an Anthropic API key
Explain this first:
"BALIA OS uses Claude (Anthropic) as the default AI engine for your agents.
For now we set up Claude only. Other AI engines can be added later depending
on what you want to build:
- When creating your own skill (Section 6), you'll choose the best AI
  for that skill — for example, Gemini for YouTube since it can analyze
  video directly, or GPT-4o for sales copy.
- After the BALIA Skill Market opens, you can also install skills built
  by other users, each with their own recommended AI engine."

Then guide me to:
1. Go to console.anthropic.com
2. Sign up or log in
3. Go to API Keys → Create Key
4. Name it "balia-os"
5. Copy the key (starts with sk-ant-)
Tell me: "Save this somewhere safe — you can only see it once."
Ask me to confirm I have the key before moving on.
Do NOT ask me to paste the key into the chat.

STEP 7 — Run OpenClaw setup
Guide me to run in the VS Code terminal:
  openclaw setup
Tell me what to expect:
- It will ask for my Anthropic API key — paste it there
- It will automatically create the folder ~/.opengoat/ (Mac) or
  $env:USERPROFILE\.opengoat\ (Windows)
  This is the BALIA OS home directory — all agent files live here.
After setup completes, guide me to run this command to start the gateway:
  Windows: $env:DEBUG="-ciao*"; openclaw gateway --force
  Mac:     DEBUG="-ciao*" openclaw gateway --force
Ask me to confirm I see:
  "✓ Gateway running on port 18789"
Tell me: "Keep this terminal tab open — it's your gateway. Open a new tab for all future commands."

Then ask me to confirm the folder was created:
- Windows: dir $env:USERPROFILE\.opengoat
- Mac:     ls ~/.opengoat
Ask me: "Do you see the .opengoat folder?"
If not, help me troubleshoot.

STEP 9 — Create the .env file
Guide me to create a .env file inside the .opengoat folder.
- Windows: In VS Code, open the folder $env:USERPROFILE\.opengoat
           Right-click in the left panel → New File → name it .env
- Mac:     In VS Code, open the folder ~/.opengoat
           Right-click in the left panel → New File → name it .env

Then paste this template:

# BALIA OS
BALIA_TOKEN=paste-your-token-here
AGENT_ID=ceo

# Anthropic API
ANTHROPIC_API_KEY=sk-ant-paste-your-key-here

# Agent model
CLAUDE_MODEL=claude-sonnet-5

# Discord Webhooks — fill these in during Section 4
# Example: DISCORD_WEBHOOK_MAYA=https://discord.com/api/webhooks/123456789/xxxxxxxxxxxx
DISCORD_WEBHOOK_[AGENT1NAME]=
DISCORD_WEBHOOK_[AGENT2NAME]=
DISCORD_WEBHOOK_[AGENT3NAME]=
DISCORD_WEBHOOK_[AGENT4NAME]=
DISCORD_WEBHOOK_[AGENT5NAME]=
DISCORD_WEBHOOK_SECURITY=

Fill in BALIA_TOKEN:
"Check the email you received after purchase.
The subject line says 'Your BALIA OS Access Token'.
Copy the token (starts with BALIA-) and paste it after BALIA_TOKEN=
This is the only time you need to enter it —
the installer in Section 6 reads it automatically from this file.
Do NOT paste it into this chat."

Fill in AGENT_ID:
"This is the ID of your CEO agent — the main agent you talk to most.
The ID is fixed: ceo. Leave AGENT_ID=ceo exactly as it appears above.
Do not change it. Install scripts and Section 4 both depend on this value."

Tell me: "Leave the Discord webhooks blank for now — you'll get the actual URLs in Section 4.
The URL format looks like: https://discord.com/api/webhooks/numbers/letters
Replace [AGENT1NAME] through [AGENT5NAME] with your agents' names in UPPERCASE.
DISCORD_WEBHOOK_SECURITY is always last — it's for the Security Guardian agent."

Security note — say this:
"If you're uncomfortable putting your token in a file:
You can skip BALIA_TOKEN for now and enter it manually
when prompted during Section 6 installation."

Tell me: "Never share this file. Never commit it to GitHub."

STEP 9b — Write the API key to the .env file
Note: The API key was already entered in STEP 7 (openclaw setup). Explain why it's needed here too.
Say: "You're setting the same API key in two places:
- openclaw setup stores it inside OpenClaw's own configuration.
- Your .env file stores it for BALIA OS agents — agents read their key from .env directly.
Both must have the same key. This is a one-time setup."
Guide me to:
1. Open the .env file in VS Code (it's in the .opengoat folder)
2. Find the line: ANTHROPIC_API_KEY=sk-ant-paste-your-key-here
3. Replace "sk-ant-paste-your-key-here" with my actual key
4. Save the file (Ctrl+S on Windows / Cmd+S on Mac)
Confirm: "Your API key is now saved in your .env file.
Never share this file or commit it to GitHub."
Do NOT ask me to paste the key into the chat.

When you finish STEP 9b, tell me: "Your environment is ready. Next we'll set up the Security Guardian — your automated setup assistant."

Start now. Ask me the first question.

🛡️ Setting Up Your Security Guardian First

Before creating your agents, we'll start your Security Guardian. From this point on, the Security Guardian will automatically check your setup, move files to the correct location if needed, and create any missing files. You don't need to worry about making mistakes — Guardian has you covered.

---

🛡️ Deploy the Security Guardian

⚠️ Warning: API Cost Runaway

[A real incident overseas — unrelated to BALIA OS] In November 2025, an AI agent at an overseas development team entered an infinite loop and kept running for 11 days without anyone noticing, resulting in an API bill of $47,000. (Source: Tech Startups / Hacker News)

AI agents can keep calling APIs without the user realizing it. To prevent this risk, Security Guardian monitors costs 24/7 and sends an immediate Discord alert when an anomaly is detected.

Always configure the following as well:

1. Set a cost alert in your AI provider's console (recommended: $3–5/day) (for Anthropic users) → https://console.anthropic.com/settings/billing
2. Verify Security Guardian cost monitoring settings (Step 2.5)

Your environment is ready.

There is one more agent in BALIA OS: the Security Guardian (security-guardian).

This agent is pre-configured by BALIA. Do not change its name, ID, or paths. Doing so will break the integration with your other agents.

---

Prerequisites: Install PM2

PM2 is a Node.js process manager. It keeps Security Guardian running automatically, even after a PC restart.

Open the VS Code terminal and paste the following command to install:

npm install -g pm2

Skip this step if PM2 is already installed.

---

Download and Run the Installer

💡 What is a Token?

Your token is the string after ?token= in the access URL from your purchase email.

Example: https://guide.baliaos.com/?token=BALIA-XXXX-XXXX-0001 → Your token is BALIA-XXXX-XXXX-0001

If you can't find the email, contact support.

Step 1 — Download the installer

In your VS Code terminal:

Windows:

Invoke-WebRequest -Uri "https://balia-os-guide.vercel.app/scripts/install_core_pack.py" -OutFile install_core_pack.py
python install_core_pack.py

Mac / Linux:

curl -o install_core_pack.py https://balia-os-guide.vercel.app/scripts/install_core_pack.py
python3 install_core_pack.py

This also places discord_send.py in $env:USERPROFILE\.opengoat\scripts\ (Windows) or ~/.opengoat/scripts/ (Mac) — every agent uses this script to post its Discord reports (see Section 4).

Step 2 — Register the Security Guardian with OpenClaw

Windows:

openclaw agents add security-guardian --workspace $env:USERPROFILE\.opengoat\workspaces\security-guardian

Mac:

openclaw agents add security-guardian --workspace ~/.opengoat/workspaces/security-guardian

This registers security-guardian so OpenClaw can route commands to it.

Step 2.5 — Verify the registration

Confirm that OpenClaw can see the agent:

openclaw agents list

You should see security-guardian listed. If it is not listed, repeat Step 2.

---

📋 guardian_config.json Customization Guide

The following settings can be changed at any time. File location:

$env:USERPROFILE\.opengoat\workspaces\security-guardian\guardian_config.json

Key	Default	Description
cost.alertHourly	1.0	Hourly API cost alert ($)
cost.alertDaily	5.0	Daily API cost alert ($)
rollback.threshold	6	Files missing before rollback triggers
rollback.autoRecovery	true	Auto-execute rollback (false = manual approval)
snapshot.intervalMinutes	10	Snapshot frequency (minutes)
snapshot.maxSnapshots	3	Number of snapshots to retain
watchdog.checkGateway	true	Monitor OpenClaw gateway
watchdog.checkWSL2	false	Monitor WSL2 (off by default)
scanner.runIntervalHours	4	Quarantine scan frequency (hours)
git.autoPushEnabled	true	Auto-backup to GitHub
git.autoPushIntervalMinutes	30	Backup frequency (minutes)

After changing settings, restart Security Guardian:

pm2 restart security-guardian

---

Step 3 — Have the Security Guardian run the installer

openclaw agent --agent security-guardian "Run: python install_core_pack.py --lang en (token loads from .env automatically). Tell me when done."

The token is read automatically from BALIA_TOKEN in your .env file.

Your agent will autonomously:

1. Authenticate your token
2. Download the Security Guardian files
3. Deploy to .opengoat/agents/security-guardian/ and .opengoat/workspaces/security-guardian/
4. Show "✓ Security Guardian deployed successfully" in the terminal

⚠️ Important: Do not change the Security Guardian's ID, name, or folder paths. Other configuration files reference this agent directly. Changing them will break the skill quarantine system.

Once the terminal shows "✓ Security Guardian deployed successfully", continue with the next step below.

INFO

agents/security-guardian/ vs workspaces/[agentid]/

BALIA OS uses two folder types for each agent:

• agents/[id]/ — OpenClaw config files (config.json, models.json) — OpenClaw reads these to launch the agent
• workspaces/[id]/ — Workspace files (SOUL, AGENTS, IDENTITY, HEARTBEAT, TOOLS, USER, SPEC) — the agent reads these at session start

The Security Guardian uses both:

• agents/security-guardian/ — config.json and models.json
• workspaces/security-guardian/ — SOUL.md, SPEC_SECURITY.md, scripts/, and more

Your custom agents use the same structure. Both folders are under $env:USERPROFILE/.opengoat/.

---

Step 3.5 — Stop the gateway, start Guardian with PM2, then restart

Once installation is complete, safely restart the gateway.

① Stop the gateway

In the PowerShell running openclaw gateway, press:

Ctrl + C

If prompted "Terminate?", press Y then Enter.

② Start Security Guardian with PM2

Open a new PowerShell and run the following one line at a time:

pm2 start $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\security_guardian.js --name security-guardian

pm2 start $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\watchdog.js --name guardian-watchdog

pm2 save

pm2 list

Confirm security-guardian and guardian-watchdog show online.

③ Restart the gateway

In the same PowerShell, run the following one line at a time:

$env:DEBUG="-ciao*"

openclaw gateway --force

Do not close this PowerShell window.

---

▶ Continue: Paste this into your AI

The Security Guardian is now running. Let's create your workspace folders and complete the setup.

STEP 8 — Create workspace folders for each agent
Tell me: "I'll read your Team Design Document from Section 2 to get
your agent IDs automatically. Please attach it now."
Read the attached Team Design Document.
Extract all 6 agent names/IDs (convert to lowercase, no spaces, use hyphens for spaces).
Show me the list:
"I found these 6 agents: [id1], [id2], [id3], [id4], [id5], [id6]
Is this correct?"
Wait for my confirmation.

Then give me the exact commands to create all 6 workspace folders at once
with the actual IDs already filled in.
Use this folder structure: workspaces\[id]\ (not workspace-[id]).
- Windows: cd $env:USERPROFILE\.opengoat
           mkdir workspaces\[id1] workspaces\[id2] workspaces\[id3] workspaces\[id4] workspaces\[id5] workspaces\[id6]
- Mac:     cd ~/.opengoat
           mkdir -p workspaces/[id1] workspaces/[id2] workspaces/[id3] workspaces/[id4] workspaces/[id5] workspaces/[id6]

After running, ask me to confirm the folders were created:
- Windows: dir $env:USERPROFILE\.opengoat\workspaces
- Mac:     ls ~/.opengoat/workspaces

STEP 10 — Final check
Run through this checklist with me one item at a time:
□ code --version → shows a version number
□ node --version → shows v22 or higher
□ openclaw --version → shows a version number
□ claude --version → shows a version number
□ VS Code has the Claude Code extension installed and logged in
□ Gateway terminal shows "✓ Gateway running"
□ .opengoat folder exists and is confirmed
□ workspaces/ subfolders created for all 6 agents
□ .env file exists in the .opengoat folder
□ BALIA_TOKEN is filled in (or noted to enter manually in Section 6)
□ AGENT_ID is set to ceo
□ ANTHROPIC_API_KEY is filled in
□ Security Guardian deployed (confirmed via terminal output)

When all boxes are checked, say:
"Installation complete. You're ready for Section 4 —
Creating Your Agent Files."

Start with STEP 8. Ask me to attach my Team Design Document.

---

🛡️ Security Guardian Audit

Your Security Guardian will now check your entire setup and fix any issues automatically.

What Guardian checks:

• All required folders exist under $env:USERPROFILE\.opengoat\
• All required files are in the correct location
• Any files in the wrong place are moved automatically
• Any missing files are created (empty — you'll fill them in Section 4)

What Guardian does NOT change yet:

• File contents (your agent personalities and settings come in Section 4)

Run the audit:

Windows:

node $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\verify_setup.js --fix

Guardian will report what it found and fixed. If everything is green, you're ready for Section 4.