{"id":51625212,"url":"https://github.com/veyralabsgroup/veyracast","last_synced_at":"2026-07-13T00:30:55.863Z","repository":{"id":368799714,"uuid":"1286884841","full_name":"veyralabsgroup/veyracast","owner":"veyralabsgroup","description":"API-first AI social content agent — generate on-brand posts and comments with Claude, schedule, and publish through official APIs (X, Instagram Graph). Multi-provider, self-hostable.","archived":false,"fork":false,"pushed_at":"2026-07-02T07:59:30.000Z","size":242,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T09:27:54.300Z","etag":null,"topics":["ai-agent","anthropic","claude","content-generation","instagram","scheduling","self-hosted","social-media-automation","twitter","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veyralabsgroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-02T07:24:46.000Z","updated_at":"2026-07-02T07:59:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/veyralabsgroup/veyracast","commit_stats":null,"previous_names":["veyralabsgroup/veyracast"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/veyralabsgroup/veyracast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veyralabsgroup%2Fveyracast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veyralabsgroup%2Fveyracast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veyralabsgroup%2Fveyracast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veyralabsgroup%2Fveyracast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veyralabsgroup","download_url":"https://codeload.github.com/veyralabsgroup/veyracast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veyralabsgroup%2Fveyracast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35406584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude","content-generation","instagram","scheduling","self-hosted","social-media-automation","twitter","typescript"],"created_at":"2026-07-13T00:30:54.134Z","updated_at":"2026-07-13T00:30:55.857Z","avatar_url":"https://github.com/veyralabsgroup.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VeyraCast\n\n**API-first AI social content agent.** Generate on-brand posts and comments with Claude (multi-provider), schedule across platforms, and publish through official APIs — X, Instagram Graph (business/creator), with LinkedIn and Bluesky on the roadmap.\n\nBuilt and maintained by [VeyraLabs](https://github.com/veyralabsgroup). A hard fork of [Riona-AI-Agent](https://github.com/David-patrick-chuks/Riona-AI-Agent) by David-patrick-chuks (MIT) — see [NOTICE](NOTICE). VeyraCast re-centers the project on official-API publishing (lower ban risk than browser automation), swaps the content engine to a pluggable multi-provider layer defaulting to Claude, and adds brand-voice guardrails and an approval queue.\n\n\u003e ⚠️ **Instagram note.** The legacy stealth-browser Instagram path is retained only as an explicit opt-in (`IG_MODE=stealth`) and is **off by default** — it violates Meta's ToS and risks account bans. The default IG path targets the official Instagram Graph API for business/creator accounts.\n\n## Run with Docker\n\nThe fastest way to run the whole stack (API + PostgreSQL):\n\n```sh\ncp .env.example .env      # add your ANTHROPIC_API_KEY, and set JWT_SECRET / SESSION_SECRET\ndocker compose up\n```\n\nThe API comes up on `http://localhost:3000` and the dashboard on `http://localhost:3000/dashboard`. PostgreSQL runs alongside it and the schema is applied on startup.\n\nThe image skips the headless-browser download by default (the official-API path doesn't need it). To use the stealth Instagram mode (`IG_MODE=stealth`), build with a Chrome-enabled base image.\n\n\u003e The compose file ships throwaway dev values for `JWT_SECRET` and `SESSION_SECRET` so it boots out of the box. **Set real values in `.env` before exposing it to anyone.**\n\n## Content engine (multi-provider)\n\nThe agent generates schema-constrained JSON via a pluggable provider. Select with `AI_PROVIDER`:\n\n| `AI_PROVIDER`         | Backend | Notes                                                                                                |\n| --------------------- | ------- | ---------------------------------------------------------------------------------------------------- |\n| `anthropic` (default) | Claude  | Structured outputs (`output_config.format`); model via `ANTHROPIC_MODEL` (default `claude-opus-4-8`) |\n| `gemini`              | Gemini  | Original behavior: JSON mode + API-key rotation                                                      |\n\nSet `ANTHROPIC_API_KEY` (and optionally `ANTHROPIC_MODEL`) for the default provider.\n\n## Training Inputs\n\nBefore running automation, you can shape the agent with:\n\n- YouTube video URLs\n- Audio files\n- Portfolio or website links\n- Documents and text files including PDF, DOC, DOCX, and TXT\n\n## Feature Summary\n\n- Instagram automation with cookies, relogin handling, posting, scheduling, and interactions\n- AI-generated captions and comments with schema-guided responses\n- Multi-account and profile-based operation support\n- PostgreSQL-backed action logs, summaries, and optional persistence\n- Simple dashboard for runtime health and latest activity\n- Logging, environment validation, and utility scripts for operations\n\n## Planned Expansion\n\n- Complete X/Twitter workflow coverage\n- GitHub automation\n- Additional analytics, reporting, and compliance controls\n\n## Installation\n\n1. **Clone the repository**:\n\n```sh\n git clone https://github.com/veyralabsgroup/veyracast.git\n cd veyracast\n```\n\n2. **Install dependencies**:\n\nThis is a **pnpm workspace** monorepo. Install [pnpm](https://pnpm.io/installation), then:\n\n```sh\npnpm install\n```\n\n3. **Set up environment variables**:\n   Copy `.env.example` to `.env` in the **repo root** and add your credentials. All apps read from this file.\n\n## Monorepo\n\nThis repository is a **pnpm workspace** with one app and shared tooling:\n\n| Package               | Path                 | Description                                 |\n| --------------------- | -------------------- | ------------------------------------------- |\n| `@veyracast/api`      | `apps/api/`          | Main API, Instagram/X automation, dashboard |\n| `@veyracast/tsconfig` | `packages/tsconfig/` | Shared TypeScript config                    |\n\n```sh\npnpm install                            # install all workspace deps\npnpm dev                                # run API (@veyracast/api)\npnpm --filter @veyracast/api \u003cscript\u003e   # run any API script\n```\n\nFull layout, paths, and contributor workflow: [Guides/Monorepo.md](Guides/Monorepo.md).\n\n## PostgreSQL Setup\n\nThe app uses PostgreSQL for action logs. If `DATABASE_URL` is not set, action logs fall back to `apps/api/logs/actionLogs.json`.\n\n### Option A: Docker (recommended for contributors)\n\n```sh\npnpm db:up\n```\n\nThis starts PostgreSQL on port `5432` with credentials that match `.env.example`.\n\n### Option B: Local PostgreSQL\n\nInstall PostgreSQL locally, create a database, and point `.env` at it:\n\n```dotenv\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/veyracast\n```\n\nCreate the database if needed:\n\n```sh\ncreatedb veyracast\n```\n\nSchema is applied automatically on startup. To run migrations manually:\n\n```sh\npnpm db:migrate\n```\n\n### Verify\n\n```sh\ndocker compose ps\n# or\npsql \"$DATABASE_URL\" -c '\\dt'\n```\n\nStop Docker Postgres:\n\n```sh\npnpm db:down\n```\n\n### Upgrading from a MongoDB fork\n\nIf your fork still uses `MONGODB_URI`, merge this branch and update `.env`:\n\n1. Remove `MONGODB_URI` / `MONGODB_REQUIRED`\n2. Add `DATABASE_URL` and `DB_REQUIRED=false` (see `.env.example`)\n3. Run `pnpm install`\n4. Start Postgres with `pnpm db:up` or use your local instance\n\nNo data migration script is provided — MongoDB action logs were optional and the app still works without a database.\n\n## Usage\n\n1. **Run the agent**:\n\n```sh\npnpm start\n# or during development:\npnpm dev\n```\n\nThis starts the API server on port 3000 and opens the dashboard at `http://localhost:3000/dashboard`. The Instagram browser only launches when you log in or trigger interactions — it does not auto-comment on its own unless `IG_AGENT_ENABLED=true`.\n\n2. **Log in and trigger interactions**:\n\n```sh\ncurl -X POST http://localhost:3000/api/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\":\"YOUR_IG_USERNAME\",\"password\":\"YOUR_IG_PASSWORD\"}'\n```\n\nThen open the dashboard or call `POST /api/interact` with your session cookie to start liking and commenting on feed posts.\n\n3. **Optional: auto-run the Instagram agent loop**\n   Set `IG_AGENT_ENABLED=true` in `.env` to run the interaction loop continuously.\n4. **Post a photo (by URL)**\n\n```sh\n curl -X POST http://localhost:3000/api/post-photo \\\\\n   -H \"Content-Type: application/json\" \\\\\n   --cookie \"token=YOUR_JWT_TOKEN\" \\\\\n   -d '{\"imageUrl\":\"https://example.com/photo.jpg\",\"caption\":\"Hello IG!\"}'\n```\n\n5. **Post a photo (file upload)**\n\n```sh\n curl -X POST http://localhost:3000/api/post-photo-file \\\\\n   -H \"Content-Type: multipart/form-data\" \\\\\n   --cookie \"token=YOUR_JWT_TOKEN\" \\\\\n   -F \"image=@/path/to/photo.jpg\" \\\\\n   -F \"caption=Hello IG!\"\n```\n\n6. **Schedule a photo post**\n\n```sh\n curl -X POST http://localhost:3000/api/schedule-post \\\\\n   -H \"Content-Type: application/json\" \\\\\n   --cookie \"token=YOUR_JWT_TOKEN\" \\\\\n   -d '{\"imageUrl\":\"https://example.com/photo.jpg\",\"caption\":\"Scheduled post\",\"cronTime\":\"0 9 * * *\"}'\n```\n\n## Dashboard\n\nOpen `http://localhost:3000/dashboard` for live status, the last IG run summary, recent\nactions, application logs, and errors.\n\n## Development\n\n| Command              | Description                                  |\n| -------------------- | -------------------------------------------- |\n| `pnpm check`         | Lint + typecheck + test + format (CI parity) |\n| `pnpm test`          | Run API test suite                           |\n| `pnpm test:coverage` | Tests with coverage report                   |\n| `pnpm lint`          | ESLint on `apps/api`                         |\n| `pnpm format`        | Prettier write                               |\n| `pnpm check:env`     | Validate required env vars                   |\n| `pnpm setup`         | Setup health check                           |\n| `pnpm dev`           | API dev server (`@veyracast/api`)            |\n| `pnpm dev:all`       | All apps in parallel                         |\n| `pnpm build`         | Build all packages                           |\n\n## Guides\n\n- [Guides/Monorepo.md](Guides/Monorepo.md) — workspace layout \u0026 commands\n- `Guides/Instagram-Bot.md`\n- `Guides/Operations.md`\n- `Guides/API.md`\n- `Guides/Env.md`\n- `Guides/Testing.md`\n- `Guides/CI.md`\n- `Guides/Scripts.md`\n- `Guides/Training.md`\n- `Guides/FAQ.md`\n- `Guides/Logging.md`\n\n## Configuration Reference\n\n### Instagram\n\n| Variable                 | Type    | Default                                                                | Description                                    |\n| ------------------------ | ------- | ---------------------------------------------------------------------- | ---------------------------------------------- |\n| `IGusername`             | string  |                                                                        | Instagram username                             |\n| `IGpassword`             | string  |                                                                        | Instagram password                             |\n| `IG_RUN_PROFILE`         | string  | `standard`                                                             | Run profile: `safe`, `standard`, `aggressive`  |\n| `IG_AGENT_ENABLED`       | boolean | `false`                                                                | Auto-run Instagram agent loop                  |\n| `IG_AGENT_INTERVAL_MS`   | number  | `30000`                                                                | Agent loop interval in ms                      |\n| `IG_DAILY_MAX_ACTIONS`   | number  | `0`                                                                    | Daily max IG actions (0 = unlimited)           |\n| `IG_MAX_POSTS_PER_RUN`   | number  |                                                                        | Max posts per run (overrides profile)          |\n| `IG_ACTION_DELAY_MIN_MS` | number  |                                                                        | Min action delay (overrides profile)           |\n| `IG_ACTION_DELAY_MAX_MS` | number  |                                                                        | Max action delay (overrides profile)           |\n| `IG_COOLDOWN_MINUTES`    | number  |                                                                        | Cooldown duration in minutes                   |\n| `IG_COMMENT_ALLOWLIST`   | string  |                                                                        | Comma-separated allowed comment terms          |\n| `IG_COMMENT_DENYLIST`    | string  |                                                                        | Comma-separated blocked comment terms          |\n| `IG_COMMENT_SENTIMENT`   | string  | `any`                                                                  | Sentiment filter: `any`, `positive`, `neutral` |\n| `IG_COMMENT_MIN_LENGTH`  | number  |                                                                        | Minimum allowed comment length (chars)         |\n| `IG_COMMENT_MAX_LENGTH`  | number  |                                                                        | Maximum allowed comment length (chars)         |\n| `IG_AD_MARKERS`          | string  | `sponsored,paid partnership,paid partnership with`                     | Comma-separated ad markers                     |\n| `IG_AD_BUTTON_MARKERS`   | string  | `learn more,shop now,sign up,install now,get offer,subscribe,book now` | Comma-separated ad button markers              |\n\n### X/Twitter\n\n| Variable    | Type   | Default | Description        |\n| ----------- | ------ | ------- | ------------------ |\n| `Xusername` | string |         | X/Twitter username |\n| `Xpassword` | string |         | X/Twitter password |\n\n### AI \u0026 APIs\n\n| Variable           | Type   | Default | Description              |\n| ------------------ | ------ | ------- | ------------------------ |\n| `GEMINI_API_KEY`   | string |         | Primary Gemini API key   |\n| `GEMINI_API_KEY_1` | string |         | Secondary Gemini API key |\n| `GEMINI_API_KEY_2` | string |         | Tertiary Gemini API key  |\n\n### Database\n\n| Variable       | Type    | Default | Description                                     |\n| -------------- | ------- | ------- | ----------------------------------------------- |\n| `DATABASE_URL` | string  |         | PostgreSQL connection URL                       |\n| `DB_REQUIRED`  | boolean | `false` | Require PostgreSQL connection (exit if missing) |\n\n### Logging \u0026 General\n\n| Variable | Type   | Default   | Description                             |\n| -------- | ------ | --------- | --------------------------------------- |\n| `LOGGER` | string | `console` | Logging backend: `winston` or `console` |\n\n## Multi-Account Support\n\nCreate `apps/api/src/config/accounts.json` (not committed) based on `apps/api/src/config/accounts.example.json`.\nThen pass `account` in `/api/login` to select which account to use.\n\n## Project Policies\n\n- `CONTRIBUTING.md`\n- `CODE_OF_CONDUCT.md`\n- `SECURITY.md`\n- `LICENSE`\n\n## Project Structure\n\n```\napps/\n  api/          @veyracast/api — REST API, agent loop, IG/X clients, dashboard\n    src/\n      Agent/      AI training, characters, schema\n      client/     Instagram \u0026 X/Twitter automation\n      config/     accounts, igProfile, logger, database\n      routes/     Express API (api.ts)\n      services/   action logs, webhooks, metrics, igChallenge\n      views/      Admin dashboard HTML\n    scripts/      env check, setup, DB migrate\npackages/\n  tsconfig/     @veyracast/tsconfig — shared compiler base\nGuides/         Documentation\ndocker-compose.yml\npnpm-workspace.yaml\n```\n\nSee [Guides/Monorepo.md](Guides/Monorepo.md) for paths, runtime directories, and CI details.\n\n## Logging\n\nWinston writes rotating logs to `apps/api/logs/`. Set `LOGGER=console` to log only to stdout. See [Guides/Logging.md](Guides/Logging.md).\n\n## Error Handling\n\nProcess-level error handlers are set up to catch unhandled promise rejections, uncaught exceptions, and process warnings. Errors are logged using the custom logger.\n\n## Contributing\n\nContributions are welcome and appreciated.\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Install deps: `pnpm install`\n4. Run checks: `pnpm check`\n5. Commit your changes and open a pull request.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [Guides/Monorepo.md](Guides/Monorepo.md).\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Stargazers\n\nThank you to all our supporters!\n\n## Community \u0026 Contact\n\n- GitHub Discussions: use the Discussions tab for Q\u0026A\n- Issues: bug reports and feature requests\n- Maintained by [VeyraLabs](https://github.com/veyralabsgroup)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveyralabsgroup%2Fveyracast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveyralabsgroup%2Fveyracast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveyralabsgroup%2Fveyracast/lists"}