openswarm/GETTING_STARTED.md

Getting Started

A step-by-step guide to get Open Swarm running locally — from clone to launch.

---

Prerequisites

Make sure the following are installed on your machine before proceeding:

Tool	Version	Check
Git	Any recent	git --version
Python	3.11+	python --version
Node.js	18+	node --version
npm	9+ (ships with Node)	npm --version

Installing prerequisites

Node.js (via nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 22
nvm use 22

---

1. Clone the repository

git clone https://github.com/<your-org>/self-swarm.git
cd self-swarm

---

2. Backend setup (Configure environment variables)

Copy the example environment file and fill in your values:

cp backend/.env.example backend/.env

Edit backend/.env with your values:

# Backend server port
BACKEND_PORT=8324

# Google OAuth (optional — needed for Google Workspace tools)
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=

---

3. Run the application

You have two options: use the provided run scripts (recommended) or start each service manually.

Option A: Run scripts (recommended)

These scripts handle virtual environments, dependency installation, and startup automatically.

Backend (starts FastAPI server):

./backend/run/dev.sh

Frontend (in a separate terminal):

./frontend/run/dev.sh

Option B: Manual startup

Terminal 1 — Backend server:

cd backend
source .venv/bin/activate
cd ..
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8324 --reload --reload-dir backend

Terminal 2 — Frontend dev server:

cd frontend
npm run dev

---

4. Open the app

Once everything is running:

Service	URL
Frontend (UI)	http://localhost:3000
Backend API	http://localhost:8324
API Docs (Swagger)	http://localhost:8324/docs

---

Google Workspace integration (optional)

To use Google Calendar, Gmail, Drive, and other Google tools from your agents, you need to set up OAuth credentials. This is a one-time setup.

a. Create a Google Cloud project

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. From the left sidebar, go to APIs & Services → Library
4. Enable the APIs you want to use:
   • Google Calendar API
   • Gmail API
   • Google Drive API
   • Google Contacts API (People API)

b. Create OAuth credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen first:
   • Choose External (or Internal if you're on a Workspace org)
   • Fill in the required app name and email fields
   • Add the scopes you enabled above
   • Add your Google account as a test user (required while the app is in "Testing" status)
4. Back on the credentials page, create an OAuth client ID:
   • Application type: Web application
   • Authorized redirect URIs: http://localhost:8324/api/tools/oauth/callback
5. Copy the Client ID and Client Secret

c. Add credentials to your .env

Paste the values into backend/.env:

GOOGLE_OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-...

d. Connect from the UI

1. Open the Tools page in the sidebar
2. Add or select a Google Workspace tool
3. Click Connect — a Google sign-in popup will appear
4. Authorize the requested scopes
5. The popup closes and the tool status changes to Connected

Your agents can now use Google Calendar, Gmail, Drive, etc. through MCP tools.

---

Instagram (built in)

The Instagram MCP server is vendored at backend/apps/instagram_mcp/ and ships with OpenSwarm. 25 tools for DMs, user/follower lookup, post engagement, and story reads, powered by instagrapi (HTTP only, no browser). No setup script, no clone, no external dependencies beyond the backend's existing Python env.

Connect from the UI

1. Open the Tools page in the sidebar.
2. Find the Instagram tile and click Connect Instagram.
3. Enter the username and password of the Instagram account the agent should use.
4. Tile flips to Connected.

The backend validates the credentials via instagrapi and saves the session to ~/.instagram_dm_mcp/sessions/<username>_session.json. Future tool calls spawn python -m backend.apps.instagram_mcp which reloads that session, so subsequent restarts skip the password prompt.

Built-in rate limiting

The server enforces per-category caps to protect the connected account from anti-abuse bans. All caps are well below Instagram's documented thresholds and apply across server restarts.

Category	Tools	per_min	per_hour	per_day
dm_send	send_message, send_photo_message, send_video_message	2	20	80
like	like_media	6	30	200
search	search_users, search_threads	30	200	1000
lookup	16 read tools	30	300	2000
modify	mark_message_seen, mute_conversation, delete_message	10	100	500

Plus randomized jitter (1.5 to 4s before DMs, 0.5 to 2s before likes, smaller elsewhere) so action timing isn't bot-perfect.

Override any cap via env var, for example:

export IG_RATE_LIMIT_DM_SEND_PER_DAY=40

State persists at ~/.instagram-mcp-rate-limits.json. When a cap is hit, the tool returns a structured {ok: false, rate_limited: true, retry_after_seconds: ...} response the agent can surface as "hit DM cap, retry in 4h" instead of failing opaquely.

---

LinkedIn (linkedin-scraper-mcp via uvx) (optional)

LinkedIn integration uses stickerdaniel/linkedin-mcp-server (PyPI: linkedin-scraper-mcp). Auth is a persistent Patchright browser profile, not OAuth and not cookies. This means one LinkedIn account per host: the saved profile at ~/.linkedin-mcp/profile/ is shared across every OpenSwarm session on this machine.

Prerequisite

uv must be on PATH (provides the uvx runner).

Connect from the UI (recommended)

1. Open the Tools page in the sidebar.
2. Find the LinkedIn tile and click Sign in with LinkedIn.
3. A Chromium window opens. Complete sign-in (2FA and captcha are supported).
4. The window closes on success; the profile is written to ~/.linkedin-mcp/profile/ and the tile flips to Connected.

Behind the scenes, Electron spawns uvx linkedin-scraper-mcp@latest --login. No credentials touch OpenSwarm; the MCP server owns the browser session.

CLI fallback (headless dev, CI, web build)

If you are not using the desktop shell, run the equivalent script from the repo root:

bash scripts/setup-linkedin-mcp.sh

Sessions and reset

• Sessions can expire. If a tool call fails with an auth error, click Sign in with LinkedIn again (or rerun the script).
• To wipe the stored profile (e.g. to switch accounts): click the Connected chip in the Tools page, or run uvx linkedin-scraper-mcp@latest --logout.

Tools exposed (17 total)

get_person_profile, get_my_profile, connect_with_person, get_sidebar_profiles, get_inbox, get_conversation, search_conversations, send_message, get_company_profile, get_company_posts, search_companies, get_company_employees, search_jobs, search_people, get_job_details, get_feed, close_session.

---

GitHub (github-mcp-server) (optional)

The official github/github-mcp-server (Go) ships as a pre-built 6.7 MB single binary. With --toolsets=all it exposes 79 tools covering repos, issues, pull requests, gists, workflows, code search, security, projects, notifications, and more. Auth is a GitHub Personal Access Token passed as GITHUB_PERSONAL_ACCESS_TOKEN.

One-time install

From the repo root:

bash scripts/setup-github-mcp.sh

The script detects your platform (macOS/Linux × x86_64/arm64), downloads the latest release tarball from GitHub Releases, and installs the binary at ~/.openswarm/bin/github-mcp-server. Re-running it upgrades to the latest version.

Connect from the UI

1. Create a Personal Access Token at https://github.com/settings/tokens. Fine-grained tokens are recommended; pick the scopes you want the agent to have.
2. Open the Tools page in the sidebar.
3. Find the GitHub tile and click Connect GitHub.
4. Paste the token and confirm. The tile flips to Connected and the server is spawned on demand for tool calls.

Notes

• No background daemon. The binary is spawned by OpenSwarm only when an agent invokes a GitHub tool.
• The token is stored locally in OpenSwarm's tool config and passed as an env var to the binary at spawn time.
• To rotate the token, click the Connected chip to disconnect, then reconnect with the new value.
• For read-only mode (safer default for unattended agents), edit the tool's mcp_config.args to include --read-only.

---

Project structure

self-swarm/
├── backend/
│   ├── apps/              # FastAPI route modules
│   │   ├── agents/        # Agent lifecycle, WebSocket, worktree management
│   │   ├── templates/     # Prompt template CRUD
│   │   ├── skills/        # Skills CRUD (synced to ~/.claude/skills/)
│   │   ├── tools_lib/     # Tool definitions CRUD
│   │   ├── modes/         # Agent mode configurations
│   │   ├── settings/      # App settings (API keys, preferences)
│   │   ├── outputs/       # Output management
│   │   └── dashboards/    # Dashboard layout persistence
│   ├── config/            # FastAPI app configuration
│   ├── data/              # Persistent JSON file storage
│   ├── run/               # Shell scripts for starting the backend
│   ├── main.py            # FastAPI entrypoint
│   ├── requirements.txt   # Python dependencies
│   └── .env               # Environment variables (not committed)
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/  # AppShell, CommandPicker, modals
│   │   │   └── pages/       # Dashboard, AgentChat, Templates, Skills, Tools, etc.
│   │   └── shared/
│   │       ├── state/       # Redux slices
│   │       ├── ws/          # WebSocket manager
│   │       └── hooks/       # Custom React hooks
│   ├── public/            # Static assets
│   ├── webpack.config.js  # Webpack bundler config
│   └── package.json       # Node dependencies
├── debugger/              # Optional debugging tool
└── README.md

---

Troubleshooting

Backend won't start — ModuleNotFoundError

Make sure you're running from the project root (not from backend/):

cd self-swarm
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8324 --reload

Frontend proxy errors / API calls failing

The frontend dev server proxies /api requests to http://localhost:8324. Make sure the backend is running first.

Mock mode vs real mode

If you see mock responses, either:

• claude-agent-sdk is not installed — run pip install claude-agent-sdk
• No Anthropic API key is configured — set ANTHROPIC_API_KEY env var or configure it in the Settings page

playwright install errors

Playwright requires browser binaries. Run playwright install after pip install to download them.