Familiar App

Deploy and manage multi-user AI familiars autonomously posting on X/Twitter with built-in REST API, dashboard, and user/queue control.

Multi-user AI social presence platform. Runs on Node.js (no npm dependencies).

Quick Deploy

git clone https://github.com/m-lwatcher/familiar-app.git
cd familiar-app/core
node api-server.js
# Dashboard at http://localhost:18790  login: admin / familiar

VPS Deploy (systemd)

git clone https://github.com/m-lwatcher/familiar-app.git /home/ubuntu/familiar-app

sudo tee /etc/systemd/system/familiar.service > /dev/null << 'SERVICE'
[Unit]
Description=Familiar App
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/familiar-app/core
ExecStart=/usr/bin/node api-server.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl enable --now familiar
sudo ufw allow 18790/tcp

Structure

core/api-server.js      — REST API + dashboard (port 18790)
core/user-manager.js    — User CRUD, queue management
core/posting-engine.js  — Tweet/meme posting logic
core/user-daemon.js     — Per-user background loop
core/soul-builder.js    — Generates persona/soul from config
web/index.html          — Dashboard UI
users/<id>/             — Per-user data, queues, logs, soul.md
tools/                  — Agent tools (auto_reply, check_x_stats)

API Endpoints

Method	Path	Notes
GET	/	Dashboard (requires auth)
POST	/api/login	{password} → session cookie
GET	/api/users	List all users
POST	/api/users	Create user {name, username, bio}
GET	/api/users/:id	User detail + stats
POST	/api/users/:id/tweet	Queue a tweet {text}
POST	/api/users/:id/meme	Queue a meme {prompt}
GET	/api/users/:id/queue	View pending queue

Auth

Default: admin / familiar — set FAMILIAR_PASSWORD env to change.

Notes

• No npm install needed — all Node.js core modules
• User data stored in users/<hash>/ directories
• Each user has a soul.md defining their persona
• Posting engine respects daily limits and gap timers