threads-auto-poster

Why Threads Auto Poster?

Consistent publishing is difficult when ideas, source links, drafts, approvals, schedules, and publishing credentials are spread across unrelated tools. Threads Auto Poster brings those steps together in a self-hosted dashboard built for creators, marketers, developers, and small teams who want a more controlled Threads automation workflow.

Use it as a Threads content planner, source-backed social media scheduler, AI-assisted post drafting workspace, or a lightweight internal publishing console. Start with manual approval, keep the kill switch enabled, and turn on automated publishing only after the complete workflow is verified.

What makes it different

• Self-hosted by design — run the dashboard and SQLite data on your own computer or VPS.
• Research before writing — maintain an approved HTTPS source registry and attach source context to content preparation.
• Human approval first — drafts are reviewed before publishing by default.
• AI is optional — the dashboard, scheduling, sources, backups, and Threads connection can run without the content agent.
• Operationally boring — SQLite WAL, backups, config transfer, integrity checks, and scoped Docker commands are included.
• Manual updates — the dashboard can notify users when a newer GitHub Release is available without overwriting the running installation.

Product preview

The main product interface is the authenticated Threads Auto Poster dashboard, where operators manage schedules, content, analytics, credentials, sources, settings, and the kill switch from one workspace.

Features

Content research and planning

• Approved HTTPS source registry with search, filters, health checks, import, and export.
• Content pillars with active-weight normalization to a total of 100%.
• Content compositions for hook, structure, CTA, source-link, language, and length rules.
• Source-aware content preparation with fallback and retry classification.
• Repository-required pillars try other approved GitHub repositories when one source is temporarily unavailable; they still fail closed when no valid repository remains.
• Post history and audit records for operational review.

Threads content workflow

• Draft, review, approve, schedule, and publish from one dashboard.
• Standalone posts are the default composition mode.
• Configurable posts per day, active hours, timezone, active days, and minimum gaps.
• Approval mode and kill switch protect the first installation.
• Threads OAuth connection with encrypted token storage in SQLite.

Threads Reply Agent

• Optional reply discovery, draft generation, review, approval, publishing, analytics, and audit trail in Dashboard → Replies.
• Disabled by default; publishing stays approval-only until an operator explicitly enables the agent and auto mode.
• Per-account policy is configurable: once allows one durable reply per target account; continuations_only permits later replies only when that same account directly replies to one of this account's recorded replies.
• Reply publishing uses an atomic claim, rechecks limits after the claim, verifies the published reply, and never blindly retries publish_unknown.
• Keyword search and profile discovery depend on Meta app capability and OAuth permission. The UI reports the official API result; it does not scrape Threads or use browser automation.

AI-assisted content generation

• Optional Hermes Agent CLI integration.
• Provider and model are operator-configurable.
• Readiness preflight prevents avoidable agent failures.
• Empty or malformed agent output is rejected instead of being scheduled as content.
• Retryable source and agent failures can retry until the slot horizon; unknown publish results are not blindly retried.

Self-hosting and operations

• Native Node.js deployment for installations that need Hermes Agent.
• Docker Compose deployment for the dashboard, SQLite, scheduler, token storage, and Threads publishing.
• SQLite WAL mode, foreign keys, busy timeout, integrity checks, and backup/restore scripts.
• One admin account with HTTP-only session cookies and login rate limiting.
• Strict production security headers and environment-aware CSP.

How it works

Approved HTTPS sources
        │
        ▼
Content pillars + compositions
        │
        ▼
Hermes Agent CLI (optional)
        │
        ▼
Draft + quality checks
        │
        ▼
Approval queue ──► Schedule ──► Threads API

The content agent is not required for the core product. You can use the source registry, dashboard, scheduling controls, backups, and Threads connection without installing Hermes Agent.

Supported CLI Tools

Threads Auto Poster currently supports Hermes Agent as its CLI content-generation runtime. More integrations should only be added when they have a tested command contract, readiness check, timeout policy, and safe failure behavior.

Hermes Agent setup

Install and configure Hermes Agent as the same operating-system user that runs Threads Auto Poster. Verify the exact provider and model before saving them in the dashboard:

printf 'Return exactly: HERMES_OK' | hermes chat --query-file - --oneshot --quiet --cli --provider YOUR_PROVIDER -m YOUR_MODEL

The command must print HERMES_OK. Then configure the matching provider and model in Pengaturan / Settings and enable the Content Agent.

THREADS is an example model name used by some operator configurations. It is valid only when the selected Hermes provider defines that model or alias.

Hermes Agent is optional for the public Docker image. The stock image does not bundle the Hermes binary; use native Node.js deployment or provide the CLI inside your own image when AI generation is required.

Quick start

1. Clone the repository

git clone https://github.com/yanstd888/threads-auto-poster.git
cd threads-auto-poster

2. Create a local environment

cp .env.example .env.local

Set real local values before starting the app. At minimum, use a strong ADMIN_PASSWORD, a random JWT_SECRET, and a separate TOKEN_ENCRYPTION_KEY. Never commit .env.local.

3. Install and start

npm ci
npm run dev

Open the URL printed by Next.js, then follow the safe first-run sequence:

1. Sign in with the admin password.
2. Leave Posting Mode on Draft / approval required.
3. Keep the Kill Switch enabled.
4. Add approved sources in Sources / Sumber.
5. Configure content pillars and compositions.
6. Verify Hermes Agent before enabling the Content Agent.
7. Connect Threads only after the public HTTPS callback is ready.

For the complete setup order, read Getting Started.

Configuration

The release uses neutral public defaults:

timezone=UTC
hermes_provider=openai-compatible
hermes_model=default
threads_username=@your_threads_username
posting_mode=approval
kill_switch=true
content_agent_enabled=false

These defaults are deliberately safe for a fresh clone. Production operators can configure their own provider, model, account, timezone, and publishing mode after verifying the complete environment.

Deployment

Native Node.js

Native deployment is the recommended path when Hermes Agent runs on the same operating-system user as the app:

npm ci
npm run build
npm run start

Keep the application behind HTTPS and a controlled access layer when exposing it remotely. The app itself should remain bound to a private interface or loopback where practical.

Docker Compose

cp .env.example .env
# edit .env; never commit it
docker compose -f co