An AI that runs your Instagram page for you.
Tell it what your page is about. Run three commands. Walk away. It writes the posts, designs the images, writes the captions, posts on schedule, replies to comments, and follows the best practices that keep accounts from getting banned.
Fully autonomous by default. Optional one-click review guardrail for the first week if you want to eyeball posts before they go live. Free to run on free-tier AI models. Runs on your own laptop or a $5/month server. No subscription.
43-second walkthrough — real ig-agent doctor, status, warmup-status runs + real dashboard navigation, narrated by Kokoro-82M (Apache-2.0, CPU).
Quickstart · Features · Architecture · Safety · Configuration · FAQ
One command. Then walk away — it's fully autonomous.
pipx install git+https://github.com/alsk1992/instagram-ai-agent.git
ig-agent setup --with-login --runThat's the whole thing. setup asks you 4 questions (niche + voice + audience + persona), opens your browser to grab a free OpenRouter key, prompts for Instagram username/password once, logs in + verifies the session, then immediately starts the orchestrator daemon. No follow-up commands, no editing .env, no copy-paste.
The daemon then generates posts on a schedule, posts them live, replies to comments, follows back niche-aligned accounts, handles the 14-day warmup ramp, backs off on rate limits, refreshes sessions. Leave it in tmux / screen / systemd and close the laptop.
Prefer to do it in stages? Drop the --run flag and the orchestrator stays off until you type ig-agent run yourself. Drop --with-login too and IG auth defers until you type ig-agent login.
If you'd rather eyeball the first 20-30 posts before handing over the keys, run setup with --review:
ig-agent setup --reviewNow the daemon still generates + schedules autonomously but queues each post for one-click approval at http://127.0.0.1:8080/review before it goes live. Flip it off any time by editing niche.yaml (safety.require_review: false).
The daemon runs itself — these are for peace of mind, not required.
ig-agent status # pulse: heartbeat, backoff, next scheduled posts, recent actions
ig-agent dashboard # same data in a browser on :8080
ig-agent pause # weekend stop without killing the daemon
ig-agent resume # back on
ig-agent doctor # diagnose in 3 seconds when something feels offBefore committing to a long run, you can fire the content pipeline once and inspect:
ig-agent generate -n 3 # generate 3 posts now
ig-agent dashboard # approve in the browser
ig-agent drain # post the approved batch immediately (first-post proof)Prerequisites — what you need on the machine before `pipx install`
- Python 3.11+ — macOS:
brew install python@3.12· Ubuntu:sudo apt install python3.12· Windows: python.org - ffmpeg — macOS:
brew install ffmpeg· Ubuntu:sudo apt install ffmpeg· Windows:winget install Gyan.FFmpeg - pipx —
python -m pip install --user pipx && pipx ensurepath
ig-agent setup will check all three and print the exact install command for anything missing.
Alternative installs — source clone, bash one-liner, Windows PowerShell, Makefile
One-line POSIX installer (clones the repo + installs everything):
curl -fsSL https://raw.githubusercontent.com/alsk1992/instagram-ai-agent/main/install.sh | bashWindows PowerShell:
irm https://raw.githubusercontent.com/alsk1992/instagram-ai-agent/main/install.ps1 | iexFrom source: git clone … && cd instagram-ai-agent && make install && make setup
For deep configuration (story mix, hashtag pools, anti-detection toggles), use ig-agent init — the 40-question advanced wizard.
Two auth paths — which one to pick
| Where you're running | Auth path | Why |
|---|---|---|
| Laptop / home WiFi | Plain username + password | Home IPs are trusted by Instagram's risk model. setup --with-login captures both, first ig-agent login call succeeds on u/p ~95% of the time. |
| VPS / server / cloud | Cookie jar from your browser | Fresh u/p from a datacenter IP triggers challenge_required on the /auth_platform/?apc=... flow almost every time in 2026. Cookie-jar path uses cl.set_settings() and skips /login entirely — zero challenge surface. |
VPS cookie capture (2026 consensus) — the setup wizard guides you:
- Install Cookie-Editor (Chrome/Firefox/Edge — Manifest V3)
- Log into instagram.com in that same browser
- Click Cookie-Editor icon → Export → JSON
- Run
ig-agent setup --with-login, pick the VPS branch, paste the JSON blob - Wizard parses, validates live against
accounts/current_user, saves to.env— only if cookies actually work
Grab a residential or 4G mobile proxy on the same ASN as the cookie extraction before the first run — cookies harvested at home running through a datacenter IP get invalidated fast.
Fresh-account warmup + email-code challenges
- Brand-new account? Leave the warmup setting alone. The agent waits ~7 days before posting, then slowly increases activity over 14 days — the single biggest lever preventing Instagram from banning automated accounts. Queue content during this time.
- Account that already posts regularly? Set
IG_SKIP_WARMUP=1in.env— posts immediately. - Email-code challenge during login? Either type it manually in the terminal, or set
IMAP_HOST/USER/PASSin.env(Gmail users: use an app password) and the agent reads the code automatically.
|
|
Anti-detection layer (details)
|
|
|
|
┌──────────────────────────────────────────────────────────────────────┐
│ ig-agent (one process) │
│ │
│ BRAIN CONTENT WORKERS │
│ ┌──────────────┐ ┌────────────────┐ ┌────────────┐ │
│ │ trend_miner │─────▶ │ format_picker │──┐ │ poster │ │
│ │ competitor │ ctx │ idea_bank │ │ │ engager │ │
│ │ watcher │──▶ feed │ generator x10 │──┤──▶──│ comment_r. │ │
│ │ reddit │ │ critic 2.0 │ │ │ follow_b. │ │
│ │ events │ │ dedup (phash) │ │ │ dm_worker │ │
│ │ rag │ │ caption gen │──┘ │ story_view │ │
│ └──────────────┘ └────────────────┘ │ health │ │
│ │ └────────────┘ │
│ ▼ ▲ │
│ ┌────────────────┐ │ │
│ │ content_queue │──────────────┘ │
│ │ engagement_q │ │
│ │ (SQLite WAL) │ │
│ └────────────────┘ │
│ │ │
└─────────────────────────────────────┼────────────────────────────────┘
▼
┌────────────────┐
│ instagrapi │
│ (transport) │
└────────────────┘
│
Instagram
Everything is scheduled by APScheduler inside a single async event loop. State lives in SQLite WAL mode — no external services, no Redis, no separate workers. Scales vertically: one account per process, one process per VPS.
Instagram's 2026 ML detector flags bot-script patterns on top of plain request inspection. The agent ships with an 8-feature behavioural layer, all on by default (toggles under human_mimic in niche.yaml):
| Feature | What it does | Gap it closes |
|---|---|---|
pre_post_scroll |
Opens the feed + marks 3–5 posts as seen before uploading | Cold-post bot-script fingerprint |
post_cooldown |
30–90min mandatory silence on likes/follows/unfollows after a post | "Posted + engaged within seconds" pattern |
comment_reply_delay |
5–60min random stagger between replies in a batch | Burst-reply signal |
first_comment_hashtags (opt-in) |
Moves hashtag block out of caption into a self-reply | 2026 ML hashtag-heavy caption downrank |
typing_delays |
Length-proportional sleep before comment/DM submit | Sub-second submission timing |
caption_entropy_check |
Rejects captions ≥85% similar to your last 10 | LLM-template drift that image-phash misses |
aspect_ratio_check |
Pre-flight checks for 4:5 / 1:1 / 9:16 before upload | Silent server-side re-compression + downrank |
rotate_client |
Recycles the TCP/HTTP-2 session every 2–4h | Long-lived connection botnet signal |
Plus the authentication layer:
- Pin device fingerprint forever —
data/device.jsonis generated once and never rotated. - Paste browser cookies into
.envto skip first-login challenges entirely. Supports all 10 IG web cookies (sessionid,ds_user_id,csrftoken,mid,ig_did,datr,rur,shbid,shbts,ig_nrcb). Full set triggerscl.set_settings()path with zero/logincall. - Geographic coherence — set
IG_COUNTRY_CODE/IG_TIMEZONE_OFFSET/IG_LOCALEto match the account's origin. - Weekly session refresh —
IG_SESSION_REFRESH_DAYS=7forces a fresh login to prevent silent server-side TTL decay. - 14-day warmup ramp — action budgets auto-scale from ~10% on day 1 to 100% by day 14.
Don't share any of: the process, the working directory, the IP, the device fingerprint. Residential proxies (Decodo / NetNut / IPBurger / Smartproxy) with sticky 24–48h sessions over IPv4 are the 2026 consensus.
- Same Reel across multiple accounts triggers network-level flagging within ~48h. Every account needs unique content.
- Bio links on day 1 = instant shadowban. Wait day 7+.
- Meta Graph API only does Reels on Business/Creator accounts (2–12 week approval). For personal accounts, instagrapi-style private API remains the only path.
Full research notes + sources in the safety deep-dive.
Everything lives in two files: niche.yaml (the spine) and .env (credentials).
The setup wizard picks a starter preset so you don't invent defaults:
niche: "home calisthenics for dads 35+"
sub_topics: [pullups, mobility, recovery]
target_audience: "office workers rebuilding fitness at home"
commercial: true # toggles licence gates
voice:
tone: [direct, dry humour, no-nonsense]
forbidden: ["hustle", "grind culture"]
persona: "ex-office worker, 40, rebuilt body at home"
cta_styles: [save for later, tag a mate, follow for more]
aesthetic:
palette: ["#0a0a0a", "#f5f5f0", "#c9a961"]
heading_font: "Archivo Black"
body_font: "Inter"
watermark: "@dadpilled"
film_strength: medium # off | subtle | medium | strong — kills the AI sheen
hashtags:
core: [calisthenics, homeworkout, bodyweighttraining]
growth: [fittips, fathersover40]
per_post: 15
formats: # distribution weights
meme: 0.30
quote_card: 0.15
carousel: 0.25
reel_stock: 0.20
reel_ai: 0.05
photo: 0.05
schedule:
posts_per_day: 1
stories_per_day: 3
best_hours_utc: [14, 18, 21]
safety:
require_review: true # toggle to false for autonomous mode
critic_min_score: 0.65Full schema: src/core/config.py::NicheConfig. The wizard (ig-agent init) walks you through every field.
OPENROUTER_API_KEY=sk-or-v1-... # at least one LLM provider
IG_USERNAME=your_handle
IG_PASSWORD=your_password
Optional but recommended for production:
IG_PROXY=http://user:pass@proxy:port # sticky residential
IG_SESSIONID=<paste from browser> # skips first-login challenge
IG_DATR=<paste from browser> # persistent device marker
IMAP_HOST=imap.gmail.com # auto-resolve email challenges
IMAP_USER=you@gmail.com
IMAP_PASS=app-password
PEXELS_API_KEY=... # for reel_stock format
See .env.example for the full list with inline explanations.
# Onboarding
ig-agent setup # one-command quick setup (4 questions, ~2 min) — fully autonomous
ig-agent setup --review # opt in to the one-click approval guardrail (training wheels)
ig-agent setup --full # extended (~15 questions: voice, palette, hashtags, formats, schedule)
ig-agent setup --minimal # take preset defaults for everything except niche name
ig-agent setup --with-login # also prompt for IG credentials inline
ig-agent setup --force # overwrite existing niche.yaml without asking
ig-agent init # legacy 40-question deep wizard
# Daily ops
ig-agent login # verify IG credentials, handle challenges
ig-agent run # start the full orchestrator (long-running)
ig-agent pause # halt all IG writes + generation (brain keeps running)
ig-agent resume # clear pause state
ig-agent status # agent pulse (heartbeat, backoff, queue, next posts, recent actions)
ig-agent doctor # diagnostic self-check with DB integrity
# Content
ig-agent generate [-n N] # generate N posts into the queue (with live progress)
ig-agent generate --format carousel # force a specific format
ig-agent generate --contrarian # force hot-take mode for this batch
ig-agent review # terminal walk-through: approve/reject pending items
ig-agent drain [--limit N] # post up to N approved items immediately
ig-agent dashboard # local web dashboard on :8080 — visual approve/reject at /review
ig-agent add-content <format> <media> # drop external media straight into the queue
# Introspection
ig-agent warmup-status # current day + scaled caps
ig-agent show-niche # dump resolved niche.yaml
ig-agent events [--push] # upcoming holidays + user dates
ig-agent reddit-questions [--push] # niche-subreddit question harvester
ig-agent index-knowledge [--clear] # rebuild RAG index from data/knowledge/
ig-agent seed-idea-bank [--fetch ...] # reload archetype library
ig-agent hashtag-review # approve discovered hashtags
# Brand LoRA / ControlNet (optional, advanced)
ig-agent lora prepare <dir> --name X --trigger W
ig-agent lora import <file.safetensors> --name X --trigger W
ig-agent lora list / activate / deactivate / remove
ig-agent controlnet set <ref.jpg> --mode pose|depth|canny
ig-agent controlnet import-model <file.safetensors>
ig-agent controlnet show / clear
make test # pytest full suite (~12s)
make lint # ruff
Every feature has tests. The suite is the contract.
If you hit a wall, run:
ig-agent doctor
It walks every dependency + config step with clear pass/warn/fail rows and a concrete action for anything broken. Cover 80% of "why isn't this working" questions in 3 seconds.
| Symptom | Usually means | Fix |
|---|---|---|
ig-agent drain returns "drained 0/1" |
Warmup is blocking posts for 7 days on a fresh account | Set IG_SKIP_WARMUP=1 in .env if your account already has post history; otherwise wait until day 8. |
Login failed: bad_password |
Actually, IG usually returns this on first login from a new IP even with correct credentials | Add a residential proxy (IG_PROXY=http://...); or paste IG_SESSIONID cookie from browser — see Safety |
No module named 'playwright' |
install.sh was interrupted or ran outside the venv | source .venv/bin/activate && pip install -e . |
ffmpeg: not found |
System package missing | macOS: brew install ffmpeg · Ubuntu: sudo apt install ffmpeg · Arch: pacman -S ffmpeg |
Terminal looks frozen during generate |
LLM calls take 10–30s each | Watch the log — tail -f logs/orchestrator.log — genuinely working, just slow |
| Dashboard shows "connection refused" | It binds to 127.0.0.1:8080 on the VPS |
SSH-tunnel: ssh -L 8080:127.0.0.1:8080 you@vps then open http://127.0.0.1:8080 locally |
| Asks for "email-code" challenge at login | IG security on new IPs | Either set IMAP_HOST/USER/PASS so the agent auto-reads the code, OR run ig-agent login in an interactive terminal and paste it manually |
Never used a terminal / Python / GitHub? Honest advice: pair with a technical friend for the first 30 minutes. The install is one line but the concepts (API keys, proxies, sessions, cookies) are a lot to absorb solo. Once setup is done the agent runs itself — you just need to get it over the initial hump.
Q: How autonomous is this actually? Do I have to babysit it?
A: No babysitting. Once you run ig-agent run, the daemon does everything — generates posts on schedule, posts them live, replies to comments, follows back, manages the warmup ramp, backs off on rate limits. No commands needed afterwards.
There's one OPTIONAL guardrail: run ig-agent setup --review (or set safety.require_review: true in niche.yaml). That makes the daemon queue each post for one-click approval at /review before it goes live. Useful for the first week while you dial in the voice; flip it off when you trust the output.
The manual commands in the CLI reference (generate, drain, review) are for testing the pipeline end-to-end on day 1 — not a daily workflow.
Q: How much does this cost to run? A: $0 to a few dollars/month. OpenRouter has 29 free models. Pexels/Pixabay/Pollinations/Freesound are free. A $5/mo VPS (Hetzner, Vultr, OVH, Contabo) is plenty. Residential proxy is optional but recommended — $10–30/mo if you take one. Image/reel generation costs nothing unless you opt into ComfyUI with paid GPU time.
Q: Will this get my account banned? A: Any Instagram automation carries risk. The agent's defaults are conservative: 1 post/day, 14-day warmup, 30–90min post-cooldown, human-review gate. The anti-detection layer closes the biggest 2026 gaps but is not magic. Use a fresh account you don't mind losing for the first few weeks while you dial in the cadence.
Q: Does it work for multi-account? A: One agent per account per VPS per IP. The architecture is single-tenant by design — multi-account sharing IPs or fingerprints is the #1 way to get the whole pool banned.
Q: Can I use it commercially (monetised page)?
A: Yes. commercial: true in niche.yaml activates licence gates that refuse non-commercial-only components (FLUX.1-dev, OpenPose, CodeFormer, pyiqa, StoryDiffusion code). Every default component is under a commercial-safe licence (MIT / Apache-2.0 / BSD / CC0 / CreativeML-Open-RAIL++).
Q: Does it support Threads / TikTok / X? A: No. Instagram only. (The architecture is portable — fork it for any platform with an unofficial Python client.)
Q: What LLM models are used? A: Whatever your LLM router has keys for. The default chain is OpenRouter (free tier) → Groq → Gemini Flash → Cerebras. Each route (captions, critic, scripts, vision) picks the best-suited free-tier model and falls back on failure.
Q: How do I add new content formats?
A: Write a generator under src/content/generators/, register it in pipeline._dispatch, add a weight field to FormatMix. See story_carousel.py for a recent example.
Contributions welcome. The repo is small enough that a casual read of src/orchestrator.py + src/content/pipeline.py orients you in ~30 minutes.
- Bug reports: open an issue with the log tail + your niche.yaml (redact secrets). Reproduce steps help a lot.
- PRs: run
make test && make lintfirst. Keep new features behind a config flag — user configs should never break on upgrade. - Discussion: for design-level questions (new format, new platform, licence concerns), open a GitHub Discussion rather than diving into a PR.
Security issues: see SECURITY.md.
MIT. Do what you want, just don't blame us when you get rate-limited.
Third-party components are listed in NOTICE.md with their individual licences. The agent's commercial=true mode refuses any non-commercial-only dependency at load time.
Built with Claude Code 4.7 (1M context) · GitHub