Rustiz documentation

Rustiz is a headless, agent-first social-media scheduler: one Rust binary, one SQLite file and no GUI. It is a Rust port of Postiz v1.47.0, licensed AGPL-3.0. Agents drive it through MCP or the CLI; a human only opens the platform login page when OAuth requires one.

Status: the port is complete, but no provider has been tested against a real platform. All provider tests use mock servers. Expect to debug the first real connection to each platform. See Porting status for the porting tracker.

Security note: JWT_SECRET encrypts customFields credentials and custom-instance OAuth client data. Provider access tokens in the Integration.token / refreshToken columns are not encrypted in this port; they are plain text in SQLite. Encrypt the database volume and every backup, and restrict access to the database file as you would to a password store. See Self-hosting §3.2.

Documentation map

Start in five commands

cargo build --release --locked -p rustiz
./target/release/rustiz init
./target/release/rustiz providers --status
./target/release/rustiz channels connect x --open
./target/release/rustiz serve

rustiz init prints an mcpServers block for a local agent; rustiz serve exposes the REST API at /public/v1, MCP at /mcp and the OAuth callbacks at /integrations/social/<provider>. The CLI works without a server when RUSTIZ_URL is unset, but posts only publish while rustiz serve, rustiz worker or rustiz mcp is running.

How a channel connects

connection is the value integrationSchema and GET /public/v1/providers report. It tells an agent what a human must do.

OAuth callbacks always use:

{FRONTEND_URL}/integrations/social/{identifier}

FRONTEND_URL has any trailing slash removed. Exceptions are called out in the master table: mastodon-custom reuses the mastodon path, tiktok-business requires a trailing slash, and x can use X_URL as its callback base.

When FRONTEND_URL does not contain the substring https (a plain-http local install), threads, slack, vk, tiktok, tiktok-business and instagram-standalone wrap the callback as https://redirectmeto.com/<FRONTEND_URL>/integrations/social/... because those platforms refuse an http:// redirect. In production, use HTTPS and the wrapper disappears.

Provider setup tiers

The tiers describe how much platform-side work stands between a fresh install and a working channel. They are about setup, not about how many features a provider supports; per-provider capabilities are on each provider page.

Tier 0 — zero developer app

Nothing to register on the platform and no server environment variable: the credentials come from the channel dialog (customFields), the instance registers the OAuth app itself (externalUrl), or the flow is a claim (moltbookClaim).

Tier 1 — instant self-serve app or bot

You create an app or bot in a self-service portal, paste a client id/secret (or bot token), register the redirect URI and connect immediately. No platform review is needed for a private/self-hosted app; Slack and Discord only review apps that are publicly distributed.

Tier 2 — sandbox/testing mode first, production review or verification

The app works immediately for accounts you add as testers/developers, but publishing to the public — or using the full API — requires app review, business verification, an audit, or a paid plan. Budget days to weeks, not minutes.

Tier 3 — paid, partner or special-access APIs

Platform rules change frequently. If a portal does not match these notes, the portal is authoritative; the code-side contract (identifier, env var names, redirect path, scopes) is in the provider page and in the Rust source.

Master provider table

All 35 registered providers, alphabetically by identifier. — means the provider needs no server environment variable (the credentials arrive through customFields, the instance, or a claim).

Legend: * = callback is tunnelled through redirectmeto.com when FRONTEND_URL is not HTTPS. † = trailing slash is required. ‡ = shares credentials with another provider.

Shared credentials and naming traps

Connecting from an agent

REST

curl -sS -X POST https://social.example.com/public/v1/integrations/x/connect \
  -H "Authorization: Bearer $RUSTIZ_API_KEY" \
  -H 'content-type: application/json' -d '{}'

The response is either {connected:true,...} or {connected:false,pending:true,connectionId,url,message}. Poll GET /public/v1/integrations/connect/<connectionId> (or connectChannelTool with that id) until it reports connected, then read GET /public/v1/integrations for the channel id.

MCP

connectChannelTool arguments:

customFields takes precedence over OAuth for any provider when it is a JSON object, so only send it to providers whose integrationSchema lists customFields.

For customFields providers, the keys and validation regexes are returned by integrationSchema (the same data the provider’s custom_fields() builds); the provider page reproduces them. Credentials are encrypted with JWT_SECRET and never returned.

Channels with inBetweenSteps (Facebook pages, Instagram accounts, LinkedIn companies, YouTube channels, Google Business locations, Tumblr blogs) need a second call:

triggerTool       { integrationId, methodName: "pages", dataSchema: [] }
channelSetupTool  { integrationId, data: { "page": "<id>" } }

methodName must be one of the provider’s declared functions (pages, companies, boards, subreddits, channels, blogs, locations, …). The provider page lists the exact follow-up for each.

Provider page checklist

Every provider page in ./providers/ follows the same shape:

1. Overview table — identifier, display name, connection mode, capabilities (comments/threads, pending/async publishing, analytics, post analytics, mentions, is_between_steps, convert_to_jpeg, max_concurrent_job, character limit).
2. Server environment variables — required_env() / required_env_alternatives(), plus optional <PLATFORM>_BASE_URL overrides.
3. Developer-app setup — portal URL, products/APIs, exact redirect URI (including redirectmeto.com and trailing-slash quirks), exact scopes requested and checked by check_scopes(), and sandbox/test-user vs production review.
4. Connecting a channel — CLI rustiz channels connect <id> and MCP connectChannelTool, including customFields keys/regexes or triggerTool/channelSetupTool follow-ups.
5. Post settings and media validation — settings_schema(), validate_settings(), check_validity(), media requirements and plug functions (run_plug / run_post_plug).
6. Implementation notes — token refresh, rate limits and port-specific quirks.

If a page and the Rust code disagree, the Rust code wins. The provider’s identifier() and ProviderInfo live in crates/rustiz-providers/src/<module>.rs; the connect flows are in crates/rustiz-server/src/connect.rs and oauth.rs.

Quick start

Rustiz is one binary. Build it, run init once, and point an agent at it. This page gets a local install working in about five minutes. For servers, Docker and TLS, see Self-hosting.

Alpha. Every provider is ported and tested against mock servers, but none has been tested against the live platform yet. Expect to debug the first real connection to each platform.

Source not public yet. The git clone URL below is a placeholder until the public release, so that command won’t work until the repository is published. The rest of this page describes a working local build once the source is available. The site’s waitlist is a disconnected preview for now; once it’s connected, choose “Self-hosting only” to be notified when the repository opens.

1. Build

You need a stable Rust toolchain. SQLite is built in. ffmpeg is optional and only used for video thumbnails.

git clone <repository-url> rustiz && cd rustiz
cargo build --release --locked -p rustiz
sudo install -m 0755 target/release/rustiz /usr/local/bin/rustiz   # optional

2. Initialise

rustiz init

This creates ~/.rustiz/ with a private config.env (holding JWT_SECRET, DATABASE_URL, FRONTEND_URL and RUSTIZ_API_KEY), the SQLite database and the first organization. It prints a JSON document that includes an mcpServers block for your agent. Running init again never replaces the secret or creates a second organization.

Back up JWT_SECRET together with the database. Stored channel credentials can’t be decrypted without it.

3. Check which platforms are ready

rustiz providers --status

Each provider reports whether it is configured, the names of any missing environment variables, and how a channel connects (oauth, customFields, telegramBot, …). Credential providers such as Bluesky, Dev.to, Medium, WordPress or Nostr need no server configuration at all. OAuth platforms need a developer app; each provider page walks through it.

4. Connect your agent

Local agent over stdio (Claude Desktop, Claude Code, Cursor, …): paste the block init printed. It looks like this and contains no secret:

{
  "mcpServers": {
    "rustiz": { "command": "/usr/local/bin/rustiz", "args": ["mcp"] }
  }
}

rustiz mcp runs the scheduler in the same process and, for a local FRONTEND_URL, also receives the platform’s login redirect. You don’t need a separate server. See MCP setup for client-specific instructions.

Or run the server for REST, remote MCP and the scheduler:

rustiz serve          # http://localhost:5000
curl http://localhost:5000/health   # -> ok

5. Connect an account and post

From the CLI:

rustiz channels connect bluesky --fields ./bluesky.json   # {"service":"https://bsky.social","identifier":"you.bsky.social","password":"app-password"}
rustiz channels connect x --open                          # after setting X_API_KEY / X_API_SECRET; opens the X login
rustiz channels list
rustiz posts create --channel <channel-id> \
  --content "<p>Hello from Rustiz</p>" \
  --date 2030-01-01T09:00:00Z --type schedule

Or ask your agent: “Connect my Bluesky account and schedule a post for tomorrow at 9:00 UTC.” It will call providersStatusTool, connectChannelTool, validatePostTool and schedulePostTool.

Posts only publish while rustiz serve, rustiz worker or rustiz mcp is running.

Next

• MCP setup: Claude, Cursor and remote clients
• CLI and REST API
• Configuration and environment variables
• Self-hosting: systemd, Docker, TLS, backups

Install: binary, systemd and Docker

Rustiz is a headless, agent-first social-media scheduler: one Rust binary, one SQLite database, no web GUI, no Redis and no Postgres. The same process serves the REST API (/public/v1), the MCP endpoint (/mcp), the OAuth “connect a channel” callbacks and the scheduler.

This document is the operator reference: install paths, every environment variable the core reads, storage and ffmpeg, reverse proxies and TLS, organizations/API keys and connecting agents over stdio or remote MCP.

Reality check. The port is complete but, as of this writing, no provider has been tested against a real platform. Provider tests use mock servers. Treat the first real connection to every platform as a debugging session. See Porting status and the per-provider pages in ./providers/.

1. Quickstart

1.1 Local, single user (no TLS)

Requirements: a Rust toolchain (stable), and optionally ffmpeg for video thumbnails. SQLite is embedded.

cargo build --release --locked -p rustiz
./target/release/rustiz init
./target/release/rustiz providers --status
./target/release/rustiz serve

rustiz init creates:

• ~/.rustiz/ (mode 0700 on Unix)
• ~/.rustiz/config.env (mode 0600) containing JWT_SECRET, DATABASE_URL, FRONTEND_URL and RUSTIZ_API_KEY
• ~/.rustiz/rustiz.db (SQLite, WAL mode)
• the first organization

It prints one JSON document with the paths, the organization, and an mcpServers block to paste into an agent. When it creates an organization it also prints the API key; when it adopts an existing one it prints api_key_location instead and never replaces the existing secret or creates a second organization.

Then:

• REST API: http://localhost:5000/public/v1/...
• MCP over HTTP: http://localhost:5000/mcp (Bearer API key)
• MCP over stdio: rustiz mcp
• Health: http://localhost:5000/health → ok

To use another directory (for example a system service):

sudo rustiz init --dir /var/lib/rustiz --name production

init writes the config file but does not persist shell environment variables. In particular, if you run FRONTEND_URL=https://social.example.com rustiz init, the generated config.env still contains FRONTEND_URL=http://localhost:5000; the same applies to DATABASE_URL. Edit the file (or export the variable on every start) before relying on it (see §3.1).

1.2 Production server (systemd + reverse proxy)

Do not expose the plain-HTTP process directly. Put Caddy, Nginx or Cloudflare in front; TLS terminates there.

sudo install -m 0755 target/release/rustiz /usr/local/bin/rustiz
sudo useradd --system --home /var/lib/rustiz --shell /usr/sbin/nologin rustiz
sudo install -d -o rustiz -g rustiz -m 0700 /var/lib/rustiz
sudo -u rustiz /usr/local/bin/rustiz init --dir /var/lib/rustiz --name production
sudo install -d -o rustiz -g rustiz -m 0700 /var/lib/rustiz/uploads
sudoedit /var/lib/rustiz/config.env

Set at least:

FRONTEND_URL=https://social.example.com
DATABASE_URL=sqlite:///var/lib/rustiz/rustiz.db
UPLOAD_DIRECTORY=/var/lib/rustiz/uploads
JWT_SECRET=<keep the value init generated>
RUSTIZ_API_KEY=<keep the value init generated>
EMAIL_PROVIDER=resend
RESEND_API_KEY=re_...
EMAIL_FROM_ADDRESS=notifications@example.com
EMAIL_FROM_NAME=Rustiz
TRUSTED_PROXY_HOPS=1

A systemd unit:

# /etc/systemd/system/rustiz.service
[Unit]
Description=Rustiz (API + MCP + scheduler)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=rustiz
Group=rustiz
WorkingDirectory=/var/lib/rustiz
Environment=RUSTIZ_CONFIG=/var/lib/rustiz/config.env
ExecStart=/usr/local/bin/rustiz serve
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/rustiz

[Install]
WantedBy=multi-user.target

If you want a separate scheduler process (for example API replicas that must not each run jobs):

# /etc/systemd/system/rustiz-worker.service
[Unit]
Description=Rustiz scheduler
After=rustiz.service
[Service]
Type=simple
User=rustiz
Group=rustiz
Environment=RUSTIZ_CONFIG=/var/lib/rustiz/config.env
ExecStart=/usr/local/bin/rustiz worker
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target

and start the HTTP tier with rustiz serve --no-worker.

1.3 Docker

The repository Dockerfile builds the binary in rust:1-slim and copies it to gcr.io/distroless/cc-debian12. The runtime image has no shell, no package manager and no ffmpeg (see §5.4).

docker build -t rustiz:local .

# One-time: create the volume, config file and database.
docker volume create rustiz-data
docker run --rm -v rustiz-data:/data rustiz:local init --dir /data

# Run the server.
docker run -d --name rustiz \
  -p 127.0.0.1:5000:5000 \
  -v rustiz-data:/data \
  -e RUSTIZ_CONFIG=/data/config.env \
  -e FRONTEND_URL=https://social.example.com \
  rustiz:local

The image already sets:

DATABASE_URL=sqlite:///data/rustiz.db
UPLOAD_DIRECTORY=/data/uploads
PORT=5000

RUSTIZ_CONFIG=/data/config.env is required if you rely on the file init wrote: without it the binary looks for ~/.rustiz/config.env and will not see the JWT_SECRET created there. Alternatively pass JWT_SECRET and RUSTIZ_API_KEY as environment variables.

A minimal Compose file:

services:
  rustiz:
    build: .
    restart: unless-stopped
    ports:
      - "127.0.0.1:5000:5000"
    environment:
      RUSTIZ_CONFIG: /data/config.env
      FRONTEND_URL: https://social.example.com
      TRUSTED_PROXY_HOPS: "1"
    volumes:
      - rustiz-data:/data

volumes:
  rustiz-data:

Run docker compose run --rm rustiz init --dir /data once before the first up. The distroless image has no shell, so docker exec ... sh will not work; use logs and the /health endpoint instead. If you run the container as a non-root user, chown the volume first.

2. What runs where

The HTTP server and the worker share only the SQLite database. Jobs are claimed with a five-minute lease and a heartbeat every 100 seconds, so a separate rustiz worker and rustiz serve can coexist. SQLite still has one writer at a time; for anything beyond a small deployment, run one worker and one API process, and use WORKER_CONCURRENCY to parallelize inside them.

rustiz with no subcommand is equivalent to rustiz serve.

In-process CLI commands (posts, channels, media, analytics, notifications, find-slot) run the HTTP router against the local database but do not start the scheduler. A post created with --type schedule stays queued until rustiz serve, rustiz worker or rustiz mcp is running.

Configuration and environment variables

3. Configuration model

3.1 Precedence and the config file

At startup, before clap parses arguments, rustiz loads a dotenv-style file:

1. --config <path>
2. RUSTIZ_CONFIG=<path>
3. ~/.rustiz/config.env (or %USERPROFILE%\.rustiz\config.env)

A file named explicitly by --config or RUSTIZ_CONFIG that does not exist is a fatal error. A missing default file is fine. rustiz init should be pointed at a directory with --dir, not at a not-yet-existing --config file, because the config file is loaded before the command runs.

The file is loaded before clap parses the command line, so PORT, HOST, DATABASE_URL and RUSTIZ_API_KEY written there are visible to the CLI as normal environment variables.

Variables already present in the real environment are not overwritten by the file. An exported variable wins even when it is empty; an empty value is then treated as unset by the application. To change a setting permanently, edit the file; to override it for one run, export it.

The parser accepts:

• KEY=value, optional export KEY=value
• # comments, blank lines
• single quotes (literal), double quotes (\n, \r, \t, \\, \", \')
• bare values, with an inline comment starting at whitespace + #
• duplicate keys: the last one wins
• a UTF-8 BOM at the start

On Unix, rustiz warns at every start if config.env is readable by group or others. Keep it 0600; it contains JWT_SECRET and the organization API key.

3.2 JWT_SECRET

JWT_SECRET is required by serve, worker and mcp; the process exits with JWT_SECRET must be set otherwise. rustiz init generates 64 random alphanumeric characters (about 380 bits).

It is not a session-signing key in this port. It is the passphrase for the AES-256-CBC (OpenSSL EVP_BytesToKey/MD5, byte-compatible with Postiz) layer that encrypts:

• customFields credential JSON (stored in Integration.customInstanceDetails)
• per-instance OAuth client information (customInstanceDetails) for externalUrl/custom-instance providers
• the pending client_info of an externalUrl OAuth state row

It does not encrypt provider access tokens in this port: the Integration.token / Integration.refreshToken columns are plain text in the SQLite file. That includes OAuth access/refresh tokens and some API keys (for example a Moltbook agent key or a Telegram chat id). Protect the database file itself (file permissions, disk encryption, encrypted backups) and treat a copy of it as a credential dump.

Changing or losing JWT_SECRET makes the encrypted custom-credential channels unreadable (Bluesky, WordPress, Lemmy, Listmonk, Medium, Dev.to, Hashnode, Nostr, Mastodon custom instances, etc.), and those channels must be reconnected. OAuth channels keep working because their tokens are not encrypted with this secret, but reconnecting them is the cleanest response to a suspected secret compromise. There is no supported rotation procedure short of reconnecting every affected channel.

3.3 Database URL

SQLite URLs use the sqlx form:

sqlite:///absolute/path/rustiz.db   # absolute (three slashes)
sqlite://relative/rustiz.db         # relative to the process CWD
sqlite::memory:                     # tests only

rustiz init percent-encodes %, ? and # in the path. The database runs in WAL mode, synchronous=NORMAL, foreign keys on, busy timeout 10s, and up to 8 pooled connections. Migrations run automatically on every connection open; rustiz migrate is a convenience that opens the database, migrates and exits.

Because WAL mode writes rustiz.db-wal and rustiz.db-shm, a naive copy of only rustiz.db while the server runs can lose recent transactions. Use sqlite3 ... ".backup ..." or stop the process (§8.3).

4. Complete environment variable reference

This section covers variables read by the core, server, engine and CLI outside individual social providers. Provider credentials (X_API_KEY, FACEBOOK_APP_ID, …) are listed in the master provider table and on each provider page.

4.1 Core

4.2 CLI, MCP and config discovery

With RUSTIZ_URL, the CLI only has the remote REST API. A channels connect OAuth flow cannot watch the server’s callback or detect the new channel; it prints the login URL and returns. Use local database mode with a loopback HTTP FRONTEND_URL if you want the CLI to wait for the login.

4.3 Storage

STORAGE_PROVIDER selects the backend: local (default), cloudflare (Cloudflare R2) or s3 (any S3-compatible store, including MinIO). An invalid value is a fatal error for the upload route and object-storage features.

Local

Cloudflare R2

S3 and S3-compatible stores

Aliases are checked in the order shown; AWS_* wins over S3_* when both are set.

Path-style requests are used (with_virtual_hosted_style_request(false)), which is what MinIO expects. The bucket (or a CDN in front of it) must serve objects publicly; the app does not generate signed URLs.

4.4 Email

Email is optional: with EMAIL_PROVIDER unset or unknown, nothing is sent and the process logs no email provider configured. Notification rows are still written to the database. To actually deliver, you also need both EMAIL_FROM_ADDRESS and EMAIL_FROM_NAME; a missing sender identity or an address without @ is skipped silently (a log line is emitted).

Resend

SMTP / nodemailer

Amazon SES

EMAIL_PROVIDER=ses uses SES’s SMTP interface, not the SES API. If either SES_SMTP_HOST or SES_SMTP_USER is set, the SMTP aliases are used; otherwise the host is derived from the region and credentials fall back to the SES access key pair.

4.5 Short links

Short-link replacement is opt-in per post (shortLink: true). The first configured provider wins in this exact order: Dub → Short.io → Kutt → LinkDrip. With none configured, links are left untouched.

Notes:

• Short.io’s domain is hard-coded as short.io; it has no domain env.
• Short.io statistics use a hard-coded https://statistics.short.io/... host; the link listing reads up to 10 pages of 150 links.
• LinkDrip expansion returns an empty string and its click count is always "0"; only creation is implemented.
• Dub sends the organization id as tenantId.

4.6 HTTP limits and proxies

The limiter is a fixed one-hour window held in process memory. Counts are not shared between replicas and reset on restart. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are sent on allowed responses; a blocked response is 429 with Retry-After. MCP gets a JSON-RPC error body; REST gets {"statusCode":429,"message":"ThrottlerException: Too Many Requests"}.

OAuth credential endpoints have fixed per-IP limits that cannot be changed:

4.7 MCP

subscriptions/listen reads the database, not an in-process bus, so it also sees changes made by a separate rustiz worker. Quick changes between polls collapse into the last one; deletions are not reported.

4.8 Worker, background jobs and media processing

4.9 Upload validation and compatibility

4.10 Provider credentials

Every OAuth/API credential is documented per provider. The shared groups that catch people out:

• Facebook Page + Instagram (Facebook Business) use FACEBOOK_APP_ID / FACEBOOK_APP_SECRET, one Meta app.
• LinkedIn + LinkedIn Page use LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET, one app and one scope set.
• Google My Business accepts GOOGLE_GMB_CLIENT_ID / GOOGLE_GMB_CLIENT_SECRET; a missing GMB id falls back to YOUTUBE_CLIENT_ID, and a missing GMB secret to YOUTUBE_CLIENT_SECRET.

See Documentation overview.

MCP setup for agents

Rustiz serves the Model Context Protocol in two ways:

The server uses the official rmcp SDK. It implements spec revision 2026-07-28 and still accepts older clients that send initialize. Tool names match Postiz’s MCP server, so prompts written for Postiz keep working.

Operator details such as the OAuth endpoints, allowed hosts and token lifetimes are in Self-hosting §7.

Local (stdio)

Run rustiz init once. It prints the exact block for your machine:

{
  "mcpServers": {
    "rustiz": {
      "command": "/usr/local/bin/rustiz",
      "args": ["mcp"]
    }
  }
}

Use the absolute path: desktop apps don’t inherit your shell’s PATH. If you ran init --dir <path>, add "env": { "RUSTIZ_CONFIG": "<path>/config.env" }. stdout carries the protocol and diagnostics go to stderr.

Claude Desktop

Open Settings → Developer → Edit Config (on macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json), merge the block above into it, and restart Claude Desktop.

Claude Code

claude mcp add rustiz -- /usr/local/bin/rustiz mcp
# remote server:
claude mcp add --transport http rustiz https://social.example.com/mcp \
  --header "Authorization: Bearer $RUSTIZ_API_KEY"

Cursor

Add the block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). For a remote server:

{
  "mcpServers": {
    "rustiz": {
      "url": "https://social.example.com/mcp",
      "headers": { "Authorization": "Bearer <api-key>" }
    }
  }
}

Other clients

Any MCP client that can launch a command (rustiz mcp) or speak Streamable HTTP works. For example, OpenAI Codex CLI in ~/.codex/config.toml:

[mcp_servers.rustiz]
command = "/usr/local/bin/rustiz"
args = ["mcp"]

Client config formats change often. If a snippet here doesn’t match your client’s documentation, follow the client’s documentation. The Rustiz side is always the same: rustiz mcp, or https://<host>/mcp with a Bearer key.

Remote (HTTP)

{
  "mcpServers": {
    "rustiz": {
      "type": "http",
      "url": "https://social.example.com/mcp",
      "headers": { "Authorization": "Bearer <api-key>" }
    }
  }
}

OAuth instead of a key in the config: leave out the header. A client that supports MCP authorization gets a 401 pointing at /.well-known/oauth-protected-resource/mcp, registers itself and opens a consent page that asks for the organization API key once. Access tokens last 1 hour and refresh tokens 30 days. Rotating the API key (rustiz org rotate-key <org-id>) revokes all of them.

If clients reach the server under a hostname other than FRONTEND_URL, add it to MCP_ALLOWED_HOSTS.

Tools

31 tools. The typical flow is in bold.

How an agent schedules a post

providersStatusTool                     -> which platforms this server can connect
integrationList                         -> connected channels and their ids
integrationSchema { platform: "x" }     -> length limit, threads, settings, functions
validatePostTool  { socialPost: [...] } -> checks without creating anything
schedulePostTool  { idempotencyKey, socialPost: [...] }
postStatusTool    { group }             -> QUEUE / PUBLISHED / ERROR, URL, retryable?

A schedulePostTool call:

{
  "idempotencyKey": "launch-note-1",
  "socialPost": [
    {
      "integrationId": "<channel id>",
      "type": "schedule",
      "date": "2030-01-01T09:00:00Z",
      "postsAndComments": [
        { "content": "<p>We just shipped.</p>", "attachments": ["https://cdn.example.com/shot.png"] },
        { "content": "<p>Docs: https://example.com/docs</p>" }
      ],
      "settings": []
    }
  ]
}

postsAndComments[0] is the post and the rest are replies (a thread). Content is HTML: wrap each line in <p>.

Resending is safe. An identical call within 10 minutes, or the same idempotencyKey within 24 hours, returns the first result instead of posting again.

type: "now" returns a durable task handle to clients that declare the MCP Tasks extension. Other clients get a normal result and poll postStatusTool.

Live updates: subscriptions/listen on rustiz://posts/<id> or rustiz://groups/<id> sends a hint whenever a post’s state changes.

Connecting accounts from an agent

connectChannelTool handles every connection mode:

• OAuth (X, LinkedIn, YouTube, …) returns {connected:false, pending:true, connectionId, url}. A human opens url once, and the agent polls with connectionId. Clients with URL elicitation get the link directly.
• Credentials (Bluesky, Dev.to, WordPress, …): pass customFields, and the account connects immediately with no browser.
• Telegram, Moltbook, Farcaster return an instruction for the human (a bot command, a claim URL, or a signer approval), then the agent polls.
• Pages and companies (Facebook, Instagram, LinkedIn Page, YouTube, Google Business, Tumblr): finish with triggerTool and then channelSetupTool.

Each provider page lists the exact fields and follow-up steps.

CLI

rustiz is the server, the scheduler, the MCP server and a CLI for agents, all in one binary. Run rustiz --help or rustiz <command> --help for the complete, current reference.

Two modes

• Local (default). Without --url, API commands run the same router in-process against DATABASE_URL. No server is needed. Posts are still only published while rustiz serve, rustiz worker or rustiz mcp is running somewhere against that database.
• Remote. With --url (or RUSTIZ_URL) and RUSTIZ_API_KEY, the CLI talks to a server over HTTP, either your own or a hosted one.

API commands print exactly one JSON document on stdout. Diagnostics go to stderr.

Global options

Real environment variables override the config file.

Running

Channels

rustiz channels list
rustiz channels connect <provider> [--open] [--fields <file|->] [--external-url <url>] \
                                   [--name <n>] [--description <d>] [--timeout 300]
rustiz channels connect-status <connectionId>
rustiz channels delete <id>

• OAuth providers print a login URL. In local mode the CLI also serves the platform callback on 127.0.0.1:<port of FRONTEND_URL> and waits until the account appears. --open launches the browser.
• Credential providers take --fields (a JSON file, or - for stdin).
• Telegram, Moltbook and Farcaster print what the human must do. Finish with connect-status.

Posts

rustiz posts list [--start <iso>] [--end <iso>] [--customer <id>]
rustiz posts get <id>
rustiz posts create --channel <id> [--channel <id> ...] --content "<p>Hi</p>" \
                    [--date <iso>] [--type draft|schedule|now] [--media <path|url> ...]
rustiz posts create --json post.json       # a full CreatePostDto, same as POST /public/v1/posts
rustiz posts update <id> [--content ...] [--date ...] [--publish] [--republish] [--json <file|->]
rustiz posts reschedule <id> --date <iso> [--publish] [--republish]
rustiz posts delete <id>                    # also deletes the other posts in its group

--type defaults to schedule, which needs --date. posts list defaults to the window from 7 days ago to 30 days ahead.

Media, analytics and slots

rustiz media list
rustiz media upload ./shot.png             # png/jpg/gif/webp/mp4/mov/webm/pdf
rustiz media upload-url https://cdn.example.com/clip.mp4
rustiz media delete <id>

rustiz analytics <channel-id> [--days 7]
rustiz notifications
rustiz find-slot <channel-id>

Using it from an agent without MCP

Any agent that can run shell commands can drive Rustiz through the CLI. The JSON output and exit codes are stable to parse:

id=$(rustiz channels list | jq -r '.[] | select(.identifier=="bluesky") | .id')
rustiz posts create --channel "$id" --content "<p>Shipped.</p>" --type now

REST API

Base URL: https://<your-host>/public/v1 (locally, http://localhost:5000/public/v1).

The paths and bodies follow Postiz’s public API, so most clients written for it only need a new base URL and key. The CLI and MCP server go through the same code, so behaviour is identical everywhere.

Authentication

Send the organization API key on every request, in either form:

Authorization: Bearer <api-key>
Authorization: <api-key>

Keys never go in URLs. Create and rotate them with rustiz org create and rustiz org rotate-key <org-id> (see CLI).

Rate limits

0 turns a limit off. Counts are kept per process.

Errors

Errors are JSON with an error message. Status codes: 400 bad request, 401 missing or invalid key, 404 not found, 409 the post is being published right now (retry later), 429 rate limited.

Posts

Create a scheduled post with a reply:

curl -sS -X POST "$RUSTIZ_URL/public/v1/posts" \
  -H "Authorization: Bearer $RUSTIZ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "type": "schedule",
    "date": "2030-01-01T09:00:00Z",
    "shortLink": false,
    "tags": [],
    "posts": [{
      "integration": { "id": "<channel id>" },
      "value": [
        { "content": "<p>We just shipped.</p>", "image": [] },
        { "content": "<p>Docs: https://example.com/docs</p>", "image": [] }
      ],
      "settings": {}
    }]
  }'

type is draft, schedule or now. value[0] is the post and the other entries are replies. inter (a number of days) repeats the post. The response lists { postId, integration, group } for each created post.

Published posts can’t be edited, because platforms keep the original. Use republish with a date to publish one again. A post in ERROR may already be live, so check the platform before you retry with publish. Deleting a post here does not remove it from the platform.

Channels (integrations)

A connection either returns { connected: true, ... } or { connected: false, pending: true, connectionId, url, message }. Hand the url to a human, then poll. See the provider overview for each connection mode.

Media

The size limit is MAX_UPLOAD_MB (default 1024). The upload rules are in Self-hosting §5.5.

Analytics and notifications

Workspace

Debugging

Outside /public/v1

Organizations, API keys and agents

7. Organizations, API keys and agents

7.1 The organization model

There are no users, passwords or teams. An organization owns channels, posts, media, notifications and API keys. The API key identifies the organization on every request. A deployment can have several organizations; each key sees only its own rows.

rustiz init --name "Acme"             # name used only when it creates the first org
rustiz org create "Acme EU"           # prints organization id + API key
rustiz org list                       # id<TAB>name, one per line
rustiz org rotate-key <org-id>        # prints the new key

rustiz org ... prints plain text, not JSON. rotate-key also revokes every MCP OAuth access/refresh token issued to that organization; clients must re-authorize or be reconfigured with the new key. Channel credentials are not deleted by a key rotation.

rustiz init is idempotent: it keeps an existing JWT_SECRET, keeps the stored API key if it still matches an organization, and otherwise adopts the first existing organization rather than creating a second one and writes that organization’s key to config.env. It only errors if the adopted organization has no API key at all (then rustiz org rotate-key <id> is the fix).

7.2 Authentication

Send the key as either:

Authorization: Bearer <api-key>

or the raw value (what Postiz sends):

Authorization: <api-key>

/mcp/{key} does not exist in this port. Keys never travel in URLs or logs. The server hashes MCP OAuth tokens with SHA-256 and compares the hash; API keys are stored in the organization row.

7.3 MCP over stdio (local agent)

rustiz init prints the exact block. It looks like:

{
  "mcpServers": {
    "rustiz": {
      "command": "/usr/local/bin/rustiz",
      "args": ["mcp"]
    }
  }
}

The key is read from RUSTIZ_CONFIG/~/.rustiz/config.env; no secret appears in the snippet. rustiz mcp also starts the scheduler and, for a loopback HTTP FRONTEND_URL, the login callback listener. You can override the key:

rustiz mcp --api-key <key>

stdout carries the MCP protocol; diagnostics go to stderr. A service manager that captures stdout must not inject banners into it.

If the machine has no config, rustiz mcp fails with a message pointing at rustiz init rather than complaining about JWT_SECRET.

7.4 MCP over HTTP (remote agent)

Endpoint: ${FRONTEND_URL}/mcp.

Bearer API key (simplest):

{
  "mcpServers": {
    "rustiz": {
      "type": "http",
      "url": "https://social.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

The transport is stateless Streamable HTTP. Tool calls normally return JSON; subscriptions/listen uses an event stream. Host must be in the allowlist: FRONTEND_URL’s host (and host:port), localhost, 127.0.0.1, plus anything in MCP_ALLOWED_HOSTS.

OAuth 2.1 + PKCE (for clients that support it): omit the Authorization header. A request without credentials gets 401 with:

WWW-Authenticate: Bearer resource_metadata="https://social.example.com/.well-known/oauth-protected-resource/mcp"

Discovery and endpoints:

Details an operator may need:

• Only response_type=code, S256 PKCE and a code challenge of at least 43 characters are accepted. resource must be ${FRONTEND_URL}/mcp or ${FRONTEND_URL}.
• Client ID Metadata Documents are supported: a client id that is an HTTPS URL (or a plain-HTTP URL when ALLOW_PRIVATE_NETWORK=true) is fetched through the SSRF-safe client, max 64 KiB, and must contain a matching client_id and redirect_uris.
• Registration accepts https URIs and http only for loopback hosts (localhost, 127.0.0.1, [::1]); at authorization the requested redirect_uri must match a registered one exactly, except that a loopback redirect may use any port (RFC 8252). javascript:, data:, file:, blob:, ftp:, ws:/wss: and fragments are rejected. At most 10 URIs, 2048 bytes each.
• Authorization codes live 5 minutes and are single-use. Access tokens live 1 hour; refresh tokens live 30 days and are rotated on use.
• The consent form is the only HTML the server renders besides the channel connect result page. It is protected by X-Frame-Options: DENY, a restrictive CSP, Referrer-Policy: no-referrer and Cache-Control: no-store.
• Registering a client grants nothing until someone enters a valid API key on the consent page.
• Revoke everything for an organization by rotating its API key.

7.5 Connecting a channel from an agent

REST and MCP share one code path.

rustiz channels list
rustiz providers --status
rustiz channels connect x --open
rustiz channels connect mastodon-custom --external-url https://mastodon.social
rustiz channels connect bluesky --fields ./bluesky.json
rustiz channels connect telegram
rustiz channels connect-status <connectionId>

--fields takes a JSON file or - for stdin. --timeout defaults to 300 seconds for the in-process OAuth wait.

MCP connectChannelTool arguments:

If customFields is present and is a JSON object, it takes precedence over the OAuth flow for any provider. Only send it to providers whose integrationSchema lists customFields.

Special flows:

• Telegram (telegramBot): with no customFields, the server returns connectionId, a word and a /connect <word> command. A human adds the bot to the target group/channel (ideally as admin), sends the command, then the agent polls with the same connectionId. With customFields.chatId it connects immediately.
• Moltbook (moltbookClaim): the server registers an agent and returns claimUrl (and possibly a verification code). The human claims it, then the agent polls.
• Farcaster (signer): the server creates a Neynar signer and returns approvalUrl/qrCode; the human approves in the Farcaster app, then the agent polls. With customFields.signerUuid of an already-approved signer it connects immediately.
• Between-steps channels (is_between_steps: Facebook pages, Instagram accounts, LinkedIn companies, YouTube channels, Google Business locations, Tumblr blogs): the OAuth login creates a channel with inBetweenSteps=true. List the choices with triggerTool and finish with channelSetupTool:

{
  "integrationId": "<id>",
  "methodName": "pages",
  "dataSchema": []
}

{
  "integrationId": "<id>",
  "data": { "page": "<page-id>" }
}

triggerTool only allows function names declared in the provider’s integrationSchema (functions array); it refreshes an expired token once and disconnects on a hard auth error. channelSetupTool rejects a channel that is already set up and reports That page is already connected as another channel on a uniqueness conflict.

OAuth providers need a human to open the URL. MCP clients that declare URL elicitation receive the link through the multi-round-trip flow; other clients get {connected:false, pending:true, connectionId, url, message} and should poll with connectionId or re-check integrationList.

7.6 Posting workflow

Typical tool order:

providersStatusTool
integrationList
integrationSchema { platform }
connectChannelTool (if needed)
validatePostTool
schedulePostTool
postStatusTool

• validatePostTool checks channel state (disabled, refresh needed, between steps), provider validate_settings, character count (HTML stripped, counted in characters), thread support and check_validity media rules. It does not create anything.
• schedulePostTool accepts socialPost[] with integrationId, date (UTC), type (draft/schedule/now), optional shortLink, settings as [{key,value}] and postsAndComments ([0] is the post, the rest are replies). attachments may be a URL string or an object with path, alt, thumbnail, thumbnailTimestamp.
• Resends are safe: an identical call within 10 minutes, or the same idempotencyKey within 24 hours, returns the first result. Reusing a key with different arguments is rejected. An in-flight or abandoned claim tells you to check postsListTool before retrying with a new key.
• With the MCP Tasks extension, type:"now" returns a durable task handle; otherwise poll postStatusTool. Task state is derived from posts and survives restarts.
• subscriptions/listen on rustiz://posts/<postId> or rustiz://groups/<groupId> sends a hint on state change; it does not carry content or errors.

Media storage and ffmpeg

5. Media storage and ffmpeg

5.1 Local storage

STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=/var/lib/rustiz/uploads
FRONTEND_URL=https://social.example.com

• Files written by uploads and generated media use <yyyy>/<mm>/<dd>/<32-char-id>.<ext>.
• The public URL is ${FRONTEND_URL}/uploads/<key>; the same process serves the directory with tower-http’s ServeDir.
• It must be a persistent volume and must be writable by the service user.
• With more than one API replica, use a shared volume or object storage. A local directory on one replica is invisible to the others.
• A reverse proxy must not strip or rewrite /uploads.

5.2 S3 / R2

STORAGE_PROVIDER=cloudflare
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_ACCESS_KEY=...
CLOUDFLARE_SECRET_ACCESS_KEY=...
CLOUDFLARE_BUCKETNAME=rustiz-media
CLOUDFLARE_BUCKET_URL=https://media.example.com
CLOUDFLARE_REGION=auto

Or:

STORAGE_PROVIDER=s3
AWS_BUCKETNAME=rustiz-media
AWS_REGION=eu-west-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_BUCKET_URL=https://media.example.com
# AWS_ENDPOINT=http://minio:9000 for MinIO

The bucket must be publicly readable over HTTPS (or fronted by a public CDN). Some providers — TikTok and TikTok Business in particular — fetch media by URL (pull_from_url) rather than accepting an upload, so a private or loopback /uploads URL cannot work for them. Public object storage is the robust choice for those providers. The media host must also be allowed in the platform’s developer app where the platform asks for verified domains.

Object keys differ slightly: with object storage, API uploads use <32-char-id>.<ext> while generated media (converted JPEGs, thumbnails) uses <yyyy>/<mm>/<dd>/<id>.<ext>. Both are addressed through CLOUDFLARE_BUCKET_URL / AWS_BUCKET_URL.

5.3 Recommended R2 lifecycle rules

R2 lifecycle rules are bucket-wide (optionally prefix-filtered) and cannot ask SQLite which objects a post still references. Therefore:

1. Always add a rule to abort incomplete multipart uploads, e.g. after 1 day. Rustiz streams uploads through object_store; a crashed process can otherwise leave billable parts behind.
2. If you need a retention policy, do not put a blanket 30-day expiration on the media prefix. Scheduled and published posts older than 30 days still reference those objects, and deleting them breaks previews, reposts and platform pulls. A 30-day rule is appropriate only for a dedicated scratch or trash prefix.
3. A safe pattern is: run a reconciliation job that copies objects no longer referenced by Media/Post rows into trash/<yyyy>/<mm>/, then apply a 30-day expiration to trash/ and let R2 delete it. Keep live media in the normal prefix with no expiry.
4. If a compliance policy requires deleting all media after 30 days, export or archive it first and accept that old posts can no longer be reposted or previewed.

5.4 ffmpeg and video thumbnails

Video thumbnails are generated by shelling out to ffmpeg:

ffmpeg -y -ss <seconds> -i <temp-input> -frames:v 1 -q:v 2 <temp-output.jpg>

The engine first runs ffmpeg -version. If the binary is missing, it logs ffmpeg not available; skipping video thumbnail and marks the media ready without a thumbnail; publishing is not failed. FFMPEG_BINARY can point at an absolute path.

ffmpeg is not needed for PNG→JPEG conversion: providers with convert_to_jpeg (TikTok and TikTok Business) are handled by the image crate at JPEG quality 100. That conversion does need UPLOAD_DIRECTORY or object storage, because the converted bytes are written back through the same storage layer.

The stock Docker image is distroless and has no ffmpeg. Two ways to add it:

Static binary (recommended; keeps distroless):

FROM rust:1-slim AS build
WORKDIR /src
COPY . .
RUN cargo build --release --locked -p rustiz

FROM gcr.io/distroless/cc-debian12
COPY --from=mwader/static-ffmpeg:9.0.2-1 /ffmpeg /usr/local/bin/ffmpeg
COPY --from=build /src/target/release/rustiz /rustiz
ENV DATABASE_URL=sqlite:///data/rustiz.db UPLOAD_DIRECTORY=/data/uploads PORT=5000
VOLUME /data
EXPOSE 5000
ENTRYPOINT ["/rustiz"]
CMD ["serve"]

Pin the mwader/static-ffmpeg tag; the latest image is large (hundreds of MiB). The static binary has no external library dependencies and works on the distroless glibc base.

Debian runtime:

FROM debian:bookworm-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends ffmpeg ca-certificates \
 && rm -rf /var/lib/apt/lists/*
COPY --from=build /src/target/release/rustiz /usr/local/bin/rustiz
# ... same ENV/ENTRYPOINT as above

This is simpler but larger and gives the container a shell and package manager. Whichever path you choose, keep /data writable and persistent.

5.5 Upload validation rules

POST /public/v1/upload (multipart field file) and POST /public/v1/upload-from-url accept only:

png jpg jpeg gif webp mp4 mov webm m4v pdf

• The extension comes from the filename, or from the URL path for upload-from-url; a URL without a recognised extension is rejected.
• The body limit is MAX_UPLOAD_MB (default 1024 MiB). The reverse proxy and Cloudflare have their own, often lower, limits.
• Remote uploads are fetched through the SSRF-safe client; only http/https is allowed. The guard blocks loopback, private, link-local and metadata addresses unless ALLOW_PRIVATE_NETWORK=true.
• Local media reads are confined to UPLOAD_DIRECTORY with lexical path normalisation; ../ and sibling prefixes such as uploads-evil are rejected.
• Remote reads have a 120-second timeout and one retry on timeout. Range requests are required by some providers; S3/R2 serve them natively, and local files are read with seek.
• Deleting media is a soft delete: the database row is marked deleted but the stored file is kept (a published post may still reference it). Reclaiming storage is an operator task; see §5.3.

Reverse proxy, TLS and OAuth callbacks

6. Reverse proxy and TLS

The server speaks plain HTTP and has no TLS listener. Terminate TLS at Caddy, Nginx, Traefik or Cloudflare. FRONTEND_URL must be the public HTTPS origin, with no path prefix: the app assumes it owns /, /public/v1, /mcp, /oauth, /.well-known and /uploads.

6.1 Caddy

social.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5000 {
        flush_interval -1
        header_up X-Forwarded-Proto {scheme}
    }
}

Caddy obtains and renews certificates automatically and appends the client address to X-Forwarded-For, so set TRUSTED_PROXY_HOPS=1 when Rustiz is reachable only through Caddy.

flush_interval -1 disables response buffering, which matters for subscriptions/listen and long MCP responses.

6.2 Nginx

server {
    listen 443 ssl http2;
    server_name social.example.com;

    ssl_certificate     /etc/letsencrypt/live/social.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/social.example.com/privkey.pem;

    client_max_body_size 1024m;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_request_buffering off;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

$proxy_add_x_forwarded_for appends the peer address; one Nginx hop means TRUSTED_PROXY_HOPS=1. If Nginx is itself behind Cloudflare, see §6.3.

6.3 Cloudflare

• Use SSL/TLS → Full (strict) with a Cloudflare Origin Certificate or a valid public certificate on the origin.
• Cloudflare’s proxy has a 100-second origin response timeout on most plans. Normal API calls and most MCP tool calls fit, but a long-lived subscriptions/listen stream may be cut. Options: give MCP a DNS-only hostname, keep the stream short and let the client reconnect, or use an Enterprise plan with a longer timeout.
• Cloudflare’s request-body limit depends on plan (commonly 100 MB). Set MAX_UPLOAD_MB and the origin proxy limit to match; otherwise large video uploads fail at the edge before reaching Rustiz.
• Do not enable “Under Attack” or a challenge on /mcp; agents cannot solve it. Use a WAF skip rule for /mcp, /oauth/* and /.well-known/* if needed.
• With Cloudflare → Nginx → Rustiz there are two appended XFF entries. Set TRUSTED_PROXY_HOPS=2 and firewall the origin so it is reachable only from Cloudflare. With Cloudflare connecting directly to Rustiz, 1 is correct. The limiter does not verify the peer address; the hop count is only safe when the origin cannot be reached directly.

6.4 OAuth callback URLs

Every provider’s redirect URI is built as:

{FRONTEND_URL}/integrations/social/{identifier}

FRONTEND_URL is trimmed of trailing slashes, so register the URI without a trailing slash unless the provider’s table explicitly shows one. The exact paths and exception cases are in the master provider table; the important ones:

• tiktok-business ends with / (.../tiktok-business/); the platform requires it and the token exchange sends the same value.
• mastodon-custom reuses /integrations/social/mastodon.
• x uses /integrations/social/x, unless X_URL overrides the base.
• threads, slack, vk, tiktok, tiktok-business and instagram-standalone wrap the URI as https://redirectmeto.com/<FRONTEND_URL>/... when FRONTEND_URL does not contain the substring https. In production this should never happen; use HTTPS.
• facebook, instagram, pinterest, reddit, linkedin, youtube, gmb, tumblr, twitch, discord, dribbble, whop and mewe are registered directly; several of them refuse plain http:// redirects even on localhost.

The callback route is GET /integrations/social/{provider}. It reads code and state from the query, consumes the one-time state row, exchanges the code and stores the channel (access tokens in plain text; customFields credentials and custom-instance client data encrypted). OAuth state lives for one hour; Telegram/Moltbook connection ids also one hour; Farcaster signers 30 minutes. A second use of the same state fails with This connection link expired, please start again.

The server does not render a dashboard. The callback renders a minimal HTML “Channel connected” / “Could not connect the channel” page.

6.5 Local OAuth without a public server

rustiz channels connect <provider> and rustiz mcp can receive the platform callback themselves, but only when FRONTEND_URL is plain HTTP on localhost or 127.0.0.1. They bind 127.0.0.1:<port> and wait. If the port is already in use by another rustiz using the same database, the command warns and waits for that process to finish the login.

If FRONTEND_URL is a public HTTPS URL or a non-loopback host, the CLI cannot receive the callback; it prints the login URL and tells you the server must handle it.

Operations: health, backups, upgrades

8. Operations

8.1 Health and readiness

curl -fsS http://127.0.0.1:5000/health        # -> ok
curl -fsS -H "Authorization: Bearer $KEY" \
  https://social.example.com/public/v1/providers/status | jq

providers/status returns, per provider:

{
  "identifier": "x",
  "name": "X",
  "configured": true,
  "missing": [],
  "connection": "oauth"
}

Only variable names are reported, never values. A provider with configured:false is refused before an OAuth URL is generated; the error names the missing variables and the redirect URI to register.

8.2 Logs

Logs go to stderr as plain-text tracing lines (the default subscriber format, with fields appended). Useful filters:

RUST_LOG=info,rustiz=debug,sqlx=warn,tower_http=info rustiz serve

Do not send MCP stdio logs to stdout. If you wrap rustiz mcp in a supervisor, route stderr to a file and leave stdout for the protocol.

8.3 Backups

Back up both the database and JWT_SECRET.

# Online, consistent backup (WAL aware).
sqlite3 /var/lib/rustiz/rustiz.db \
  ".backup '/var/backups/rustiz-$(date +%F).db'"

# Or stop the service and copy the database plus any -wal/-shm files.
systemctl stop rustiz
cp -a /var/lib/rustiz/rustiz.db* /var/backups/
systemctl start rustiz

Also back up config.env (or at least JWT_SECRET and RUSTIZ_API_KEY) and the upload directory or bucket. A database restored without the original secret can no longer decrypt customFields credentials or custom-instance client information, so those channels must be reconnected. Provider access tokens remain readable because they are stored in plain text in the database — which also means a database backup is a bearer-credential backup: encrypt it and restrict access to it.

Test restores on a separate copy. Do not run two servers against the same SQLite file over NFS or a network filesystem.

8.4 Upgrades

1. Back up.
2. Build/copy the new binary.
3. rustiz migrate (or just start; migrations run automatically).
4. Restart serve and worker; graceful shutdown closes MCP subscription streams.
5. Check /health and providers --status.

Schema migrations are applied in order and are not automatically reversible. Read the release notes before a downgrade.

8.5 Scaling

• One SQLite file supports one writer at a time. Scale vertically first: WORKER_CONCURRENCY, MCP_SUBSCRIPTIONS_MAX_STREAMS, REQUEST_LIMIT.
• Multiple serve replicas are possible only with a shared database; SQLite on a shared local volume is not safe across hosts. Object storage is required for media if replicas do not share a volume.
• Rate limits are per process, so N replicas mean N× the configured budget.
• Use one worker unless you have measured lease contention; the job table uses five-minute leases and heartbeats and can handle several workers, but SQLite write contention is the practical limit.
• Long-lived MCP streams are cheapest on a single instance; a proxy with buffering disabled is mandatory.

8.6 Security checklist

• FRONTEND_URL is HTTPS and matches the registered redirect URIs.
• JWT_SECRET is random and stable, config.env is 0600, and both are backed up. It protects custom credentials, not OAuth tokens.
• The SQLite file and its backups are encrypted at rest: provider access tokens (including OAuth tokens and some API keys) are stored in plain text in the database.
• Rustiz binds 127.0.0.1 (or a private interface) behind a TLS proxy.
• ALLOW_PRIVATE_NETWORK is unset unless the deployment is single-tenant and the network is trusted.
• API keys are distributed over a secret manager, not chat or URLs.
• TRUSTED_PROXY_HOPS matches the real proxy chain and the origin is firewalled to those proxies.
• The /data volume and UPLOAD_DIRECTORY are writable only by the service user.
• The object bucket is public only for media, and its write credentials are not exposed to clients.
• Backups are encrypted and restore-tested.
• RUST_LOG does not log request bodies containing credentials (the port redacts bodies stored in Errors, but proxy logs are your responsibility).

Troubleshooting

9. Troubleshooting

For platform-specific registration steps, see the provider pages in ./providers/ and the setup tiers in Documentation overview.

Bluesky (bluesky)

Bluesky is the reference client for the AT Protocol. Rustiz speaks XRPC over plain HTTP, authenticates with a handle + app password (there is no OAuth app and no redirect URI), and publishes app.bsky.feed.post records to the account’s PDS. Video is uploaded to Bluesky’s separate video service and polled asynchronously.

• Rust source: crates/rustiz-providers/src/bluesky.rs
• Upstream port: bluesky.provider.ts
• Editor: Normal
• Connection mode: customFields
• No developer app, no OAuth, no app review.

Overview

Server Environment Variables

required_env() returns nothing:

#![allow(unused)]
fn main() {
fn required_env(&self) -> &'static [&'static str] {
    &[]
}
}

required_env_alternatives() is not overridden.

There is no BLUESKY_BASE_URL. The PDS origin is a per-channel customFields.service value, not a server env var. BLUESKY_VIDEO_BASE_URL only changes the video upload host; it does not change the PDS.

rustiz providers --status reports bluesky as configured even before any account is connected, because the credentials arrive per channel.

Step-by-Step Developer App Setup

There is no Bluesky developer portal application to create. The “app” is an app password created by the account owner.

1. Prepare the account

1. Sign in at https://bsky.app.
2. Open Settings → Privacy and security → App Passwords (the direct URL is https://bsky.app/settings/app-passwords).
3. Choose Add App Password, name it Rustiz, and copy the generated password. It looks like xxxx-xxxx-xxxx-xxxx.
4. Keep the account’s normal password out of Rustiz. An app password can be revoked individually without changing the account password.

Bluesky app passwords are intended exactly for this: third-party clients that need to create records but should not be able to change the account password or email. They still act as the account for posting, deleting and reading.

2. Know the service URL

The handle alone does not identify the PDS: use the PDS origin. service is trimmed of a trailing slash. It must be https unless SSRF protection is disabled.

3. Redirect URI

There is none. Bluesky’s password/session flow has no browser redirect, no redirect_uri, no client id and no client secret. connectChannelTool with customFields completes synchronously.

4. Scopes

Bluesky app passwords have no scope selection. The provider’s info.scopes is a Postiz compatibility field only; check_scopes() is never called. The app password grants whatever the account can do through com.atproto.server.createSession, except account-administration endpoints that AT Protocol blocks for app passwords.

5. Sandbox / testing vs production

• There is no Bluesky sandbox and no app review. The same app password works against production immediately.
• Use a secondary Bluesky account, or a self-hosted PDS, for tests. A test post is public on the account’s profile.
• Video uploads require a verified email address on the Bluesky account and consume the account’s daily video quota. A brand-new test account may not be allowed to upload video.
• If the account has 2FA enabled and createSession answers AuthFactorTokenRequired, the Rust port has no authFactorToken handling and reports invalid credentials. The provider’s tool tip says to disable 2FA; the safer modern alternative is to rely on an app password, but the code does not implement the 2FA challenge.
• Revoking the app password immediately invalidates the stored session; there is no refresh path (see below).

Connecting a Channel (CLI & MCP)

customFields keys

Exact service validation string:

/^(https?:\/\/)?((([a-zA-Z0-9\-_]{1,256}\.[a-zA-Z]{2,6})|(([0-9]{1,3}\.){3}[0-9]{1,3}))(:[0-9]{1,5})?)(\/[^\s]*)?$/

CLI

Create a JSON file:

{
  "service": "https://bsky.social",
  "identifier": "alice.bsky.social",
  "password": "abcd-efgh-ijkl-mnop"
}

rustiz channels connect bluesky --fields ./bluesky.json

# or pipe it
printf '%s' '{"service":"https://bsky.social","identifier":"alice.bsky.social","password":"abcd-efgh-ijkl-mnop"}' \
  | rustiz channels connect bluesky --fields -

A successful credential connection is immediate:

{ "connected": true, "pending": false, "name": "Alice" }

No browser opens and no callback is served. --open / --timeout do nothing useful for this provider.

MCP connectChannelTool

{
  "provider": "bluesky",
  "customFields": {
    "service": "https://bsky.social",
    "identifier": "alice.bsky.social",
    "password": "abcd-efgh-ijkl-mnop"
  }
}

integrationSchema reports:

{
  "type": "customFields",
  "headless": true,
  "requiresHuman": false
}

There is no follow-up. Call integrationList for the channel id.

Important: do not omit customFields

If connectChannelTool is called for bluesky without customFields, connect.rs falls through to the OAuth path. Bluesky::generate_auth_url() returns the random state string as both url and state (a legacy of the upstream base class), so the agent receives a “login URL” that is not a URL and no channel is created. Always send the credential object.

Likewise, an empty object {} is still an object: connect_custom() encodes it and authenticate() fails with Invalid credentials. Send all three keys.

Provider functions (triggerTool)

None. functions() is empty. integrationSchema.functions is [].

Post Settings & Media Validation

settings_schema()

Bluesky does not override the trait default:

{ "type": "object", "properties": {}, "additionalProperties": true }

There are no provider-specific settings. __type is added by the engine. The post text and media are the only inputs; there are no reply-gate, language, label or quote settings.

validate_settings()

Not overridden: every settings object is accepted.

check_validity()

The provider checks exactly two rules, per post (each Vec<ValidityMedia> is one entry in the thread):

#![allow(unused)]
fn main() {
if posts.iter().any(|post| {
    post.iter().any(|media| media.path.contains("mp4")) && post.len() > 1
}) {
    return Ok(Some("You can only upload one video per post.".into()));
}
if posts.iter().any(|post| post.len() > 4) {
    return Ok(Some("There can be maximum 4 pictures in a post.".into()));
}
}

• One .mp4 may be the only media in a post.
• An .mp4 plus any other media is rejected.
• More than four media items is rejected, even if some are videos.
• The contains("mp4") check is case-sensitive; VIDEO.MP4 bypasses the rule, while has_extension() later treats it as a video. This is a port bug: a .MP4 plus an image can reach the upload path and the video branch silently ignores the image.
• There is no file-size check, no aspect-ratio check, no alt-length check and no video-duration check.

Media requirements

Images are uploaded with Content-Type: application/octet-stream, not their real image MIME type. AT Protocol’s uploadBlob records the request content type on the blob; a PDS may therefore store the blob as application/octet-stream and clients may not render it. If images appear as downloads instead of pictures, this is the first thing to fix.

Facets

The provider reproduces @atproto/api’s RichText.detectFacets:

• Mentions: (^|\s|\()@handle where the handle is a valid domain; resolved with com.atproto.identity.resolveHandle and stored as a app.bsky.richtext.facet#mention with a did.
• Links: http(s)://… or a bare domain with a valid TLD; trailing punctuation and unmatched ) are trimmed; stored as app.bsky.richtext.facet#link.
• Hashtags: # or full-width ＃ at the start of a word; tag trimmed of punctuation; max 64 UTF-16 code units; stored as app.bsky.richtext.facet#tag.

Offsets are UTF-8 byte offsets, as AT Protocol requires. Facets are omitted when the list is empty.

No link preview cards. Rustiz never creates an app.bsky.embed.external card. A URL in the text is a clickable facet, not a card with title/description/image.

Plugs

run_plug() implements two methods (both are @Plug-style automations, run after the post is live):

Fields arrive as JSON; plug_text() accepts strings, numbers and booleans and stringifies them. An empty or non-numeric likesAmount becomes 0, so the plug fires on the next run regardless of likes. run_post_plug() is not overridden and returns Unsupported.

Implementation Notes & Gotchas

• There is no OAuth. generate_auth_url() is a legacy stub that returns the state string as the URL. The only working connect path is customFields; without it the agent gets a bogus URL (see above).
• Login on every publish. The stored accessJwt is not reused for publishing: get_agent() calls com.atproto.server.createSession with the stored handle/app password for every post, comment, mention search and plug. This is simple but burns the createSession rate limit (30 per 5 minutes, 300 per day per account) and means a revoked app password fails at publish time even if the channel was connected successfully.
• No refresh. refresh_token() returns an empty token and expires_in: 0. The stored refreshJwt is never used. A 4xx login (other than 429) is classified as refresh_token, so the channel is marked for reconnect. There is no com.atproto.server.refreshSession implementation.
• Two-phase duplicate protection. Bluesky uses a prepare/commit handshake in pending_data:
  1. post_pending() starts the video job (if any) and stores {jobId, message, media}.
  2. check_post_status() polls the video job. When ready, finalize_post() is called.
  3. The first finalize_post() only sets attempting=true, confirmed=false and returns Pending.
  4. The next check_post_status() sees attempting=true and sets confirmed=true; it returns Ready.
  5. The second finalize_post() performs the upload/createRecord and returns Completed. If a create attempt is uncertain, the next check_post_status() sees attempting && confirmed and refuses with “Bluesky may have already published this post…”. This is deliberate: createRecord is the one irreversible step and is called with execute (no retry, no 401 reclassification).
• Preparation failures are disarmed. If login or blob upload fails before createRecord, prep_failure() clears attempting/confirmed and increments prepFailures; after 4 failures it returns “Could not prepare the post for Bluesky, nothing was published”. This lets the workflow retry without a false duplicate warning.
• Video polling. start_video_upload() calls com.atproto.server.getServiceAuth with aud=did:web:<PDS host>, lxm=com.atproto.repo.uploadBlob, exp=now+30m, then streams the MP4 to app.bsky.video.uploadVideo?did=…&name=…. getJobStatus is public (no auth). The job must reach blob != null; JOB_STATE_FAILED is a hard error. The blocking upload_video() waits 18 × 30 s (~9 minutes).
• Image resizing is aggressive. The loop shrinks by 10% until the encoded file is about 976 KiB, not Bluesky’s current 2 MB. A 12 MP photo may be reduced more than necessary. The re-encode uses image::guess_format (JPEG is the fallback when the format cannot be guessed).
• GIFs become static. image::load_from_memory decodes the first frame; the re-encode is a still image. Bluesky displays GIFs as static images anyway, but do not expect animation.
• Only .mp4 is recognized as video. has_extension(path, "mp4") is the only video test. A .mov, .webm or .m4v is treated as an image: it is decoded with the image crate and uploaded as an image blob, which will fail or produce a non-video embed. Transcode non-MP4 video to MP4 before posting.
• No size pre-check. check_validity() only counts items. A 20 MB image is accepted by validation, resized locally, and then uploaded; a 400 MB video is accepted by validation and rejected by the video service or the engine’s upload limits. MAX_UPLOAD_MB and the reverse proxy limit are the practical caps.
• Facet resolution can fail softly. If resolveHandle fails, the mention facet is still emitted with an empty did; Bluesky may reject the record or ignore the facet. There is no per-facet error surfaced to the user.
• 300 characters is not the whole limit. Bluesky’s lexicon also has a 3,000-byte ceiling per post. The engine counts chars() on the stripped text, not graphemes and not bytes. This is stricter than Bluesky for emoji sequences (a family emoji counts as several chars) but does not protect against 300 four-byte characters exceeding 3,000 bytes.
• Rate limits. Current Bluesky documented limits: 3,000 requests per 5 minutes per IP; createSession 30 per 5 minutes and 300 per day per account; record writes cost points (create 3, update 2, delete 1) with 5,000 points per hour and 35,000 per day. Video has separate daily quotas. Because Rustiz logs in for every post, a high-volume queue can exhaust createSession before it exhausts record writes.
• max_concurrent_job = 6 is the provider’s own concurrency cap. It does not reserve rate-limit budget.
• Video requires a verified email and a profile. Bluesky rejects video uploads from accounts without a verified email (and, in some clients, a display name/avatar). Rust surfaces the video job’s failure as “Could not upload video, job failed”.
• Release URL is https://bsky.app/profile/{did}/post/{rkey}, built from the at:// URI returned by createRecord. The stored post_id is the full AT URI, not just the rkey.
• Threads. comment() calls app.bsky.feed.getPostThread?uri=…&depth=0 to get the parent cid and the root ref. For a top-level parent, it uses the parent as both root and parent. For a reply, it reads record.reply.root. The reply’s text and media go through the same facet and embed logic.
• Mentions. mention() calls app.bsky.actor.searchActors?q=… and maps handle to id, displayName to label, avatar to image. The engine’s mention_format() prefixes @.
• No analytics. Bluesky has no analytics() / post_analytics() implementation in this port, even though the public AppView exposes counts.
• SSRF check. is_safe_public_https_url() requires https, rejects localhost, resolves the host and rejects private/blocked IPs. It runs only during authenticate(), not on every publish; a PDS that resolves publicly at connect time and privately later is not rechecked.
• Custom PDS caveat. service_auth() derives the video audience from the PDS host as did:web:<host>. A self-hosted PDS that is not addressed by a did:web matching its hostname may fail video service auth; text and image posts still work.

References

• AT Protocol / Bluesky API overview: https://docs.bsky.app/docs/get-started
• App passwords: https://bsky.app/settings/app-passwords
• com.atproto.server.createSession: https://docs.bsky.app/docs/api/com-atproto-server-create-session
• com.atproto.repo.createRecord: https://docs.bsky.app/docs/api/com-atproto-repo-create-record
• com.atproto.repo.uploadBlob: https://docs.bsky.app/docs/api/com-atproto-repo-upload-blob
• Video service (app.bsky.video.*): https://docs.bsky.app/docs/api/app-bsky-video-upload-video
• Rich text facets: https://github.com/bluesky-social/atproto/tree/main/packages/api/src/rich-text
• Bluesky rate limits: https://docs.bsky.app/docs/advanced-guides/rate-limits
• Postiz Bluesky setup: https://docs.postiz.com/self-host/providers/bluesky
• Postiz Bluesky settings: https://docs.postiz.com/public-api/providers/bluesky

Dev.to (devto)

Dev.to (Forem) is an article provider: the post body is Markdown and the publish call creates an article with published: true. Rustiz talks to the Forem API with a personal API key. There is no developer app, no OAuth exchange, no scope model and no app review.

• Rust source: crates/rustiz-providers/src/devto.rs
• Upstream port: dev.to.provider.ts
• Editor: Markdown
• Connection mode: customFields

Overview

Server Environment Variables

required_env() returns no variables:

#![allow(unused)]
fn main() {
fn required_env(&self) -> &'static [&'static str] {
    &[]
}
}

required_env_alternatives() is not overridden. There is nothing to register, so rustiz providers --status reports devto as configured even before any user has supplied an API key.

required_env() purposefully does not include DEVTO_BASE_URL; it is only an optional override read through Config::base_url("DEVTO", ...).

Step-by-Step Developer App Setup

There is no developer portal application to create.

1. Sign in to the Dev.to account that should publish the articles.

2. Open Settings → Extensions: https://dev.to/settings/extensions.

3. Click Generate API Key (the UI may call it Generate New Key).

4. Copy the key. Treat it as a password: it can create, update and unpublish articles on that account. There are no scopes to select.

5. Optionally verify it before connecting:

   curl -s https://dev.to/api/users/me \
     -H "api-key: $DEVTO_API_KEY"
   

   The response contains id, name, username and profile_image, which are exactly the fields Rustiz stores during authenticate.

Products and permissions

• No products or APIs must be enabled.
• No OAuth scopes exist for a personal API key.
• The key is account-wide. There is no per-publication key.
• To publish under an organization, the account must already be a member of that organization and the organization id must be supplied in the post settings.

Sandbox / testing mode

Dev.to has no sandbox environment. The API acts on the production account.

• Use a secondary Dev.to account for tests, or accept that a test article is public.
• Rustiz always sends published: true; there is no draft mode in this provider. The provider’s “schedule” is Rustiz waiting until the scheduled time before calling Dev.to.
• A useful safe check is GET /api/users/me, which creates nothing.

Production app review

There is no app review. The same key works in production immediately. Dev.to’s general terms and per-endpoint rate limits still apply.

Connecting a Channel (CLI & MCP)

The credential payload has exactly one key:

CLI

Create a JSON file (or pipe JSON on stdin with --fields -):

{ "apiKey": "dv_xxxxxxxxxxxxxxxxxxxxxxxx" }

rustiz channels connect devto --fields devto-key.json

# or without a file
printf '%s' '{"apiKey":"dv_xxxxxxxxxxxxxxxxxxxxxxxx"}' \
  | rustiz channels connect devto --fields -

A successful credential connection is immediate and returns:

{ "connected": true, "pending": false, "name": "Your Dev.to name" }

MCP

connectChannelTool arguments:

{
  "provider": "devto",
  "customFields": {
    "apiKey": "dv_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

There is no follow-up step. Call integrationList to get the channel id. The returned connection object is {"type":"customFields","headless":true,...} in integrationSchema. Use --fields / customFields; --external-url / externalUrl is not the credential path for this provider.

Provider functions (triggerTool)

MCP examples:

{ "integrationId": "int_...", "methodName": "tags" }

{ "integrationId": "int_...", "methodName": "organizations" }

Both functions have an empty input_schema / dataSchema.

Post Settings & Media Validation

settings_schema()

CLI note: the simple rustiz posts create --channel <id> --content "..." form cannot pass provider settings. Use rustiz posts create --json post.json with a CreatePostDto (type, date, posts[].settings, …) when any of these fields are required.

The schema marks title and tags as required. validate_settings is more lenient about a missing tags value (it treats it as an empty list), but the schema and normal editor flow require it.

Example object form (public API / CLI --json):

{
  "title": "Shipping a Rust scheduler",
  "main_image": { "id": "m1", "path": "https://cdn.example/cover.png" },
  "canonical": "https://blog.example/shipping-rust-scheduler",
  "organization": "1234",
  "tags": [
    { "value": 1, "label": "rust" },
    { "value": 2, "label": "api" }
  ]
}

MCP settings is an array of {key, value} pairs:

{
  "settings": [
    { "key": "title", "value": "Shipping a Rust scheduler" },
    { "key": "tags", "value": [
      { "value": 1, "label": "rust" },
      { "value": 2, "label": "api" }
    ] }
  ]
}

The engine adds "__type": "devto" automatically if it is missing.

validate_settings() rules

1. title must exist and be a string; at least 2 Unicode scalar values.
2. canonical, if present and a string, must be a valid URL unless it contains the internal (post: placeholder. The Rust URL check accepts an empty string, an http(s):// URL, or a www. host with a dot and a non-space tail.
3. organization, if present and not null, must be a string.
4. tags, if present and not null, must be an array with at most 4 items. Each item must be an object with a numeric value and a string label.
5. main_image, if present and not null:
   • must be an object;
   • id must be a string;
   • path must be a string;
   • if RESTRICT_UPLOAD_DOMAINS is set, path must contain that value;
   • the path (query string stripped) must end in .png, .jpg, .jpeg, .gif, .webp or .mp4 (case-insensitive);
   • alt, if present, must be a string;
   • thumbnail, if present, must be a non-empty valid URL.

Media requirements

• Dev.to only receives a cover image URL in main_image.path; the media / attachments array on the post is ignored.
• The cover is not uploaded by Rustiz. It must already be a public URL.
• The extension check allows .mp4, but Dev.to’s main_image is a cover image; a video URL will almost certainly be rejected by the platform.
• Body images are whatever Markdown the post contains (Dev.to side-loads external images referenced in the article).

check_validity() is the trait default (Ok(None)). Dev.to has no additional media-count, dimension or file-type rule in this provider; the only media validation is the main_image extension/domain check in validate_settings().

Plugs

No @Plug or @PostPlug methods are implemented. run_plug() and run_post_plug() use the trait defaults and return ProviderError::Unsupported.

Implementation Notes & Gotchas

• The article is always public. post() hard-codes published: true. There is no draft or native scheduling option. A scheduled post is only delayed by Rustiz; once the publish job runs, the article is live.
• No Accept header. Forem’s v1 documentation says v1 requests should send Accept: application/vnd.forem.api-v1+json. Rustiz sends only api-key. The tests and ordinary api-key endpoints tolerate this, but if Dev.to returns an unexpected response or HTML, missing version negotiation is the first thing to check.
• Organization id is sent as a JSON string. The schema and validation require organization to be a string, and post() sends "organization_id": "<string>". Dev.to’s article schema documents organization_id as an integer. If Dev.to rejects the organization, this type mismatch is the cause. Omitting organization avoids it.
• (post: canonical placeholder is only skipped in validation. If a caller passes a string containing (post:, validate_settings accepts it, but post() still sends the non-empty value as canonical_url. Only omit the field to leave the canonical URL out.
• Tag ids are replaced by labels. The tool returns {value: <id>, label: <name>}, but publishing sends only label. Renaming a tag in the editor changes what is sent; the numeric id is not used by Dev.to on create.
• tags[].value must be a number in Rustiz. docs.postiz.com shows string values in some examples. The Rust validator explicitly requires Value::is_number; string tag values fail with each tag needs a numeric \value` (tag id)`.
• organizations is an N+1 call and capped at 1000 articles. It reads /api/articles/me/all?per_page=1000; organizations that never appear on those articles are not listed. Large accounts can be slow.
• No refresh. authenticate stores the key with a 100-year expires_in and refresh_token: Some(""). refresh_token() returns an empty access token with expires_in: 0. A genuine 401 therefore cannot be repaired by refresh; reconnect the channel with a fresh key.
• 401 maps to refresh. The HTTP layer treats an unclassified 401 as RefreshToken (test unauthorized_is_a_refresh), so a revoked key shows up as a refresh/reconnect problem.
• Canonical uniqueness. A 422 body containing Canonical url has already been taken is converted to the actionable message Canonical URL already exists.
• Max concurrency 3. The provider limits itself to three simultaneous jobs. Dev.to also enforces its own per-endpoint limits (article creation is commonly limited to 10 requests per 30 seconds); the generic HTTP layer retries 429/500 up to three times with the configured 5-second delay.

References

• Forem API overview: https://developers.forem.com/api
• Forem API v1 reference: https://developers.forem.com/api/v1
• Dev.to API key page: https://dev.to/settings/extensions
• Postiz provider settings: https://docs.postiz.com/public-api/providers/devto
• Postiz posting rules: https://docs.postiz.com/general/platforms/overview

Discord (discord)

Discord is a guild-based chat platform. Rustiz uses OAuth only to discover the guild and the application’s bot user; every publish, comment and mention call authenticates as the Rustiz bot with DISCORD_BOT_TOKEN_ID. A channel is a guild channel id, and comments are published in a thread created on the original message.

• Rust source: crates/rustiz-providers/src/discord.rs
• Upstream port: discord.provider.ts
• Editor: Markdown
• Connection mode: oauth

Overview

Server Environment Variables

required_env() returns exactly:

#![allow(unused)]
fn main() {
fn required_env(&self) -> &'static [&'static str] {
    &["DISCORD_CLIENT_ID", "DISCORD_CLIENT_SECRET"]
}
}

required_env_alternatives() is not overridden.

rustiz providers --status reports Discord as configured when only DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET are set. It does not check DISCORD_BOT_TOKEN_ID. The OAuth login can succeed and the channel can appear in channels list, but every publish fails with 401: Unauthorized until the bot token is set. Set both credentials and the bot token.

DISCORD_BASE_URL is used for both API calls and browser-facing release URLs. If you point it at a mock server, the releaseURL values are mock URLs too.

Step-by-Step Developer App Setup

1. Create the application

1. Sign in to Discord and open the Developer Portal.
2. Click New Application, name it (e.g. Rustiz), accept the terms.
3. Upload an App Icon (1024×1024 max) under General Information and save. Postiz’s own docs call this required: without an icon, the Discord CDN avatar URL that Rustiz builds can 404 when the channel is added.
4. Open OAuth2 and copy the Client ID and Client Secret.

2. Add the redirect URI

In OAuth2 → Redirects, click Add Redirect and paste the exact value:

https://social.example.com/integrations/social/discord

Local development examples:

http://localhost:5000/integrations/social/discord   # Docker / rustiz serve default
http://localhost:4200/integrations/social/discord   # upstream Postiz dev UI

Discord requires HTTPS for production redirect URIs. It accepts http://localhost (and sometimes loopback IPs) for local development. The URI must match exactly, including scheme, host, port, path and trailing slash. Do not append a query string.

There is no redirectmeto.com wrapper for Discord.

3. Create the bot and copy the token

1. Open Bot in the Developer Portal.
2. Set the bot’s username/avatar as desired.
3. Click Reset Token and copy the token. This is the value for DISCORD_BOT_TOKEN_ID — it is a token, not an application id.
4. The bot does not need privileged intents for this integration: it sends messages and uses the member search endpoint, which Discord documents as usable without the Guild Members intent. Do not enable privileged intents unless you need the full member list or member events.

If you later want the full member list (GET /guilds/{id}/members), the GUILD_MEMBERS privileged intent is required. Apps under 10,000 guild-installed users can toggle privileged intents themselves; above that, Discord requires an application and review.

4. Set the environment and restart

DISCORD_CLIENT_ID="…"
DISCORD_CLIENT_SECRET="…"
DISCORD_BOT_TOKEN_ID="…"
FRONTEND_URL="https://social.example.com"

Restart rustiz serve, rustiz worker and rustiz mcp, then check:

rustiz providers --status

5. Redirect URI (exact)

Discord::redirect_uri() is:

#![allow(unused)]
fn main() {
format!(
    "{}/integrations/social/discord",
    self.ctx.config.frontend_url()
)
}

FRONTEND_URL is trimmed of trailing slashes, so the registered value has no trailing slash. The same string is sent to /oauth2/authorize and to /api/oauth2/token; a mismatch returns invalid_request / Invalid "redirect_uri" in request.

6. Scopes and permissions requested

The authorize URL is:

https://discord.com/oauth2/authorize
  ?client_id=<DISCORD_CLIENT_ID>
  &permissions=377957124096
  &response_type=code
  &redirect_uri=<urlencoded redirect>
  &integration_type=0
  &scope=bot+identify+guilds
  &state=<state>

377957124096 is the permission bit set:

integration_type=0 means GUILD_INSTALL. The app must allow guild installs in the Developer Portal (the default for a bot app). The bot scope adds the bot to the selected server with the requested permissions; identify and guilds give Rustiz the user token it uses to read the guild id and application/bot identity.

authenticate() calls check_scopes() with ["identify", "guilds"] against the token response’s scope. The bot scope is not checked, but the URL requests it. If Discord returns a scope string without identify or guilds, the connection fails with NotEnoughScopes.

The user performing the install needs Manage Server on the target guild.

7. Sandbox / testing vs production app review

Discord has no sandbox guild or test-mode OAuth client. Use a dedicated test server.

• Under 100 guilds: the bot works immediately; no Discord review. Create a private test server, install the app there, and post to a test channel.
• 100+ guilds: Discord App Verification is required. The owner must verify identity through Stripe and complete the App Verification checklist in the Developer Portal. This is for public scale, not for a private deployment.
• App Directory listing is optional and separate from verification.
• Privileged intents: not needed here; if enabled, the threshold is 10,000 guild-installed users (2026 policy), after which Discord requires an application and 90-day review.
• Bot token vs OAuth token: production and test use the same application model. Rotating the bot token in the portal immediately breaks every existing Rustiz channel until DISCORD_BOT_TOKEN_ID is updated and the processes are restarted. Reconnecting the channel does not fix a bad bot token; Rustiz’s own error says so.

Connecting a Channel (CLI & MCP)

CLI

rustiz channels connect discord --open

• The login URL is printed to stderr; --open launches the browser.
• With a local FRONTEND_URL, the CLI serves the callback on the frontend port and waits up to --timeout seconds (default 300) for the new channel.
• With a public HTTPS FRONTEND_URL, the CLI prints the URL and exits; the server handles the callback. Poll with rustiz channels connect-status <connectionId> or rustiz channels list.

The connect response’s id is the guild id, name is the application name, and username is the bot user’s username. The channel’s internal_id is the guild id.

MCP connectChannelTool

Start:

{ "provider": "discord" }

The tool returns:

{
  "connected": false,
  "pending": true,
  "requiresHuman": true,
  "connectionId": "…",
  "url": "https://discord.com/oauth2/authorize?...",
  "message": "A human must open this URL and log in. Then poll with connectionId or check integrationList."
}

Give the url to a human with Manage Server, then poll:

{ "connectionId": "…" }

Choosing the channel after connecting

is_between_steps = false; there is no channelSetupTool step. The guild id is already stored. Use triggerTool with the channels function to list the guild’s text, announcement and forum channels:

{
  "integrationId": "<discord channel id>",
  "methodName": "channels",
  "dataSchema": []
}

The result is [{ "id": "123456789012345678", "name": "general" }]. Only channel types 0 (text), 5 (announcement) and 15 (forum) are returned. Choose an id and put it in the post settings:

{ "channel": "123456789012345678" }

channelSetupTool is not used by Discord. It is only for providers whose connection creates a temporary parent channel that must be narrowed to a page, board, company or YouTube channel.

What not to send

• customFields — Discord is OAuth only; the generic path would treat the object as an authorization code.
• externalUrl — Discord is not self-hosted. The generic path calls the provider’s external_url(), which returns Unsupported("externalUrl").

Post Settings & Media Validation

settings_schema()

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "minLength": 1,
      "description": "Channel must be an id"
    }
  },
  "required": ["channel"],
  "additionalProperties": true
}

channel is a snowflake id, not a #name. Usernames and channel names are not resolved.

validate_settings() rules

• channel must exist and be a string.
• It must not be empty.
• No snowflake-format check, no permission check, no “is this channel in the connected guild?” check. A wrong or foreign channel id passes validation and fails at Discord with 50001 / 10003.

check_validity()

Not overridden. There are no pre-flight media or length rules; Discord’s API enforces them. In particular:

• The 2000-character message limit is reduced to 1980 by max_length(), but a post with media still has the same 2000-character cap.
• Discord’s attachment size limit depends on the server’s boost tier. Rustiz does not pre-check; Discord returns 40005 (Request entity too large) and the provider maps it to “Attachment exceeds Discord’s size limit”.

Media requirements

send_message_with_media() builds a multipart request:

POST {DISCORD_BASE_URL}/api/channels/{channel}/messages
Authorization: Bot <DISCORD_BOT_TOKEN_ID>
Content-Type: multipart/form-data

payload_json = {
  "content": "<converted mentions>",
  "attachments": [
    {"id": 0, "description": "Picture 0", "filename": "image.png"},
    ...
  ]
}
files[0] = <streamed file>
files[1] = ...

• Every media item is attached in one message. Discord allows up to 10 attachments per message; Rustiz does not split a larger list.
• The file part has no explicit MIME type. Discord usually sniffs it, but a mislabeled file can be rejected.
• The whole form is rebuilt on each retry because a consumed media stream cannot be replayed.
• Discord’s per-file size limit applies (10 MB on unboosted servers; higher with boosts). There is no pre-flight size check.
• alt text is not sent; the attachment description is hard-coded as Picture <index>.

Threads and comments

supports_comments = true.

• The first comment calls POST /api/channels/{channel}/messages/{post_id}/threads with {"name":"Thread","auto_archive_duration":1440} and then sends the comment into the new thread channel.
• Later comments are supposed to reuse the same thread channel.
• Known limitation: comment() receives last_comment_id as the previous comment’s message id, and then uses it as a channel id for the next POST /channels/{id}/messages. For a thread with three or more entries, the third entry targets a message id as if it were a channel and fails. Only the first reply is reliable. See “Implementation Notes” below.
• Comment media follows the same multipart path as a normal post.
• releaseURL for a comment is the thread message URL.

Plugs

No @Plug or @PostPlug methods. run_plug() and run_post_plug() use the trait defaults and return ProviderError::Unsupported.

Implementation Notes & Gotchas

• Posting is bot-only. post() and comment() ignore the OAuth access_token entirely and send Authorization: Bot <DISCORD_BOT_TOKEN_ID>. The OAuth token is used only during connect/refresh. A missing or rotated bot token makes every publish fail even though the channel looks connected.
• The bot must be in the guild. The bot scope in the authorize URL adds it during install. If someone removes the bot from the server, channels returns 50001 and posts fail. Reconnecting the channel does not re-add the bot; use the install URL again.
• Channel lookup uses the guild id. channels() calls /api/guilds/{integration.internal_id}/channels. If the token response did not include guild.id (for example the bot was already installed and Discord omitted the guild object), internal_id is empty and the lookup hits /api/guilds//channels. This is why the integration id is the guild id, not the bot id.
• Avatar URL can 404. authenticate() builds {CDN}/avatars/{bot.id}/{bot.avatar}.png. If the bot has no custom avatar, bot.avatar is empty and the URL ends in /.png; Postiz’s docs tell you to upload an app icon for this reason. A 404 avatar does not stop publishing.
• Refresh response loses identity fields. refresh_token() returns only the new token and application name; id, picture and username are empty. The engine only writes the token columns, so this is normally harmless. Do not call refresh_token() and then treat the result as a full account snapshot.
• OAuth token lifetime. Discord access tokens expire after 7 days (expires_in: 604800) and the refresh token can rotate. The engine does not refresh Discord proactively (refresh_cron = false); it refreshes on a 401 from the OAuth token. Because posting uses the bot token, a stale OAuth token has no effect on publishing.
• Thread bug for 3+ comments. Engine chaining (post_flow.rs) passes last_comment_id = previous comment's post_id. For Discord that is a message id. comment() treats it as a channel id on every reply after the first. With exactly two entries (post + one comment) the code uses the root post id and works. With three or more, the third and later comments fail. There is no stored thread_id in pending_data/PostResponse, so the provider cannot recover the thread channel id later.
• Forum channels are listed but not really supported. channels() includes type 15 (forum), but posting to a forum channel requires creating a thread with a thread_name/forum payload, not a plain /channels/{id}/messages call. Expect a forum channel to fail or create an unexpected message. Prefer text (0) or announcement (5) channels.
• Mentions: role labels are often empty. mention() returns roles with id = "&<role id>" and label = name.split('@').nth(1). A normal role name like Moderator has no @, so the label is an empty string. The id is still correct and mention_format() converts [[[@&123]]] to <@&123>, but a UI that displays label will show blank role options.
• Mentions: member search needs the bot in the guild. members/search is called with the bot token and a query; it returns members whose username or nickname starts with the query. No privileged intent is required by current Discord docs for this endpoint (the full member-list endpoint is different). @here and @everyone are special-cased and not cached.
• Mentions: @here/@everyone are plain text. mention_format() returns the name unchanged for those two, unlike normal users/roles which are wrapped as [[[@…]]] and converted to <@…>/<@&…>. A ping only happens if the bot’s role has MENTION_EVERYONE; the fixed permission integer 377957124096 does not request it. Grant it separately if you need mass mentions.
• Mention conversion is regex-based. convert_mentions() replaces [[[@...]]] with <@...> for both users and roles. A literal [[[@...]]] in the message will be converted; there is no escaping mechanism.
• Error mapping is substring-based. handle_errors() looks for Discord error codes anywhere in the body:
  • 50001 → Bot doesn't have access to this channel
  • 50013 → Bot lacks permission to send messages in this channel
  • 10003 → Channel no longer exists
  • 40005 → Attachment exceeds Discord's size limit
  • 20028 → Rate limited by Discord (retry)
  • 401: Unauthorized → Discord rejected the Rustiz bot token, reconnecting will not help A 401 with a different body is treated as a refresh error by the shared HTTP layer, which then cannot help because posting uses the bot token.
• Only 200/201 count as success in send(). send_message_with_media bypasses this and accepts 200..=202. channels, create_thread and change_nickname use send_json, so a 204 would be treated as failure.
• Rate limits. Discord allows up to 50 requests/second per bot globally, plus per-route buckets (message creation is roughly 5 requests per 5 seconds per channel). Rustiz sets max_concurrent_job = 5, which is safe for global throughput but can still hit a per-channel bucket if several queued posts target the same channel. 429 responses are retried by the shared HTTP layer.
• Invalid-request Cloudflare ban. Discord temporarily blocks IPs that make too many 401/403/429 requests (10,000 per 10 minutes). A bad bot token or a removed channel in a retry loop can contribute. Fix the token/channel instead of letting the queue retry indefinitely.
• change_nickname needs the guild id and permission. It calls PATCH /api/guilds/{id}/members/@me with {"nick": name}. The requested permission bit set does not include CHANGE_NICKNAME; a bot can normally change its own nickname, but a restrictive role setup may return 403.
• max_length is 1980, not 2000. The 20-character margin is intentional, but the provider does not count UTF-16 code units or grapheme clusters the way Discord does. Emoji-heavy posts can still exceed Discord’s real limit.
• Markdown editor. Discord renders Markdown, so the engine passes the content through the Markdown editor path. Discord’s flavor differs from CommonMark in tables, headings and mentions; test formatting in a real channel.
• Release URL uses the configurable base. It is {DISCORD_BASE_URL}/channels/{guild}/{channel}/{message}. With the default base this is the normal discord.com/channels/... link; with a mock base it is not a usable Discord link.
• No analytics or plugs. Discord has no analytics methods, no post analytics and no plug hooks in this port.

References

• Discord Developer Portal: https://discord.com/developers/applications
• OAuth2: https://docs.discord.com/developers/topics/oauth2
• Permissions and bit fields: https://docs.discord.com/developers/topics/permissions
• Rate limits: https://docs.discord.com/developers/topics/rate-limits
• App verification (100+ guilds): https://support-dev.discord.com/hc/en-us/articles/23926564536471
• Privileged intents (10,000-user threshold): https://support-dev.discord.com/hc/en-us/articles/6205754771351
• Search Guild Members: https://docs.discord.com/developers/resources/guild#search-guild-members
• Postiz Discord setup: https://docs.postiz.com/providers/discord

Dribbble (dribbble)

Dribbble is an OAuth 2.0 provider for publishing a single shot image. The API is a single-shot multipart upload: one image is posted to POST https://api.dribbble.com/v2/shots, and the new shot id is read from the Location response header. Dribbble creates shots asynchronously, but the Rustiz port marks the post Completed as soon as the API accepts the upload.

• Rust source: crates/rustiz-providers/src/dribbble.rs
• Upstream port: dribbble.provider.ts
• Editor: Normal (plain text)
• Connection mode: oauth

Read the gotchas before using this provider. The refresh path is a faithful port of an upstream copy/paste bug that calls Pinterest with Pinterest credentials and a Pinterest redirect URI. The team setting is validated but never sent. See Implementation Notes & Gotchas.

Overview

Server Environment Variables

required_env() returns exactly two variables:

#![allow(unused)]
fn main() {
fn required_env(&self) -> &'static [&'static str] {
    &["DRIBBBLE_CLIENT_ID", "DRIBBBLE_CLIENT_SECRET"]
}
}

required_env_alternatives() is not overridden. provider_status will refuse to generate a login URL if either is empty.

required_env() deliberately omits PINTEREST_*, even though refresh_token() reads them. That means rustiz providers --status says Dribbble is configured while refresh support is silently incomplete.

Step-by-Step Developer App Setup

1. Sign in to Dribbble and open https://dribbble.com/account/applications/new.

2. Fill in:

   • Name — for example Rustiz.

   • Description — required by the form.

   • Website — your product or instance URL.

   • Callback URL / Redirect URI — enter exactly:

     {FRONTEND_URL}/integrations/social/dribbble
     

     For example https://social.example.com/integrations/social/dribbble. Do not add a trailing slash.

3. Save the application and copy the Client ID and Client Secret. The Postiz Dribbble guide says both are 64 characters long.

4. Set them on the server:

   DRIBBBLE_CLIENT_ID="your-client-id"
   DRIBBBLE_CLIENT_SECRET="your-client-secret"
   FRONTEND_URL="https://social.example.com"
   

5. Restart Rustiz and check:

   rustiz providers --status | jq '.[] | select(.identifier=="dribbble")'
   

   configured should be true with no missing variables.

Spelling warning. The Postiz documentation page for Dribbble currently shows DRIBBLE_CLIENT_ID / DRIBBLE_CLIENT_SECRET (two bs, not three) and a redirect path /integrations/social/dribble (one fewer b). Those are typos. This Rust port uses DRIBBBLE_CLIENT_ID / DRIBBBLE_CLIENT_SECRET and the correct /integrations/social/dribbble path. Register the URI the Rust code actually builds, not the one on that docs page.

Products and APIs

Dribbble has no products or API-enablement console. Registering an OAuth application is enough. The scopes are requested in the authorization URL.

Exact OAuth scopes

scopes() returns:

#![allow(unused)]
fn main() {
vec!["public", "upload"]
}

The authorization URL sends scope=public+upload (a space-separated list, encoded as +). authenticate() calls check_scopes(&["public", "upload"], token["scope"]); the token response must contain both scopes. upload is the one that permits POST /v2/shots; public is read-only public information.

Redirect URI details

The exact URI is:

{FRONTEND_URL (trailing slash trimmed)}/integrations/social/dribbble

Examples:

Dribbble’s own OAuth docs say the redirect host and port must exactly match the registered callback; if redirect_uri is omitted, the registered callback is used. Rustiz always sends it, both at authorize time (URL-encoded) and at token exchange (unencoded; see gotchas). There is no redirectmeto.com relay in this provider: the value is built directly from FRONTEND_URL, so an HTTP local frontend registers an HTTP URI and an HTTPS production frontend registers an HTTPS URI.

Sandbox / testing mode

Dribbble has no sandbox environment and no separate test app mode.

• The app is usable immediately after registration; there is no documented review/approval queue.
• Use a secondary Dribbble account for tests. A shot created through the API is public; there is no draft status in the create-shot API.
• scheduled_for exists in Dribbble’s API but requires a Pro account, team membership or a team; Rustiz does not expose it. The scheduler controls when Rustiz calls the API.
• Rate limits are 60 requests per minute and 1,440 per day per authenticated user. Watch X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 is returned when exceeded.
• The application can be suspended for abuse, spam or API misuse. That is a platform enforcement action, not a pre-publication review.

Production app review

No separate app-review step is documented in the OAuth flow: registration is self-serve and the app can authorize users immediately. Dribbble’s API terms reserve the right to refuse API access at any time and to throttle or block a service, and an app can be suspended for abuse or API misuse. For a public or commercial integration, treat access as discretionary and read the API terms before launch.

Connecting a Channel (CLI & MCP)

CLI

# Opens the Dribbble authorization page in the default browser.
rustiz channels connect dribbble --open

# Without --open: the URL is printed to stderr and the command waits.
rustiz channels connect dribbble

# Remote server: open the URL yourself, then poll.
rustiz channels connect-status <connectionId>

In local/in-process mode the CLI serves the callback on the port of FRONTEND_URL (if it is this machine) and waits for the new channel. On success it prints the channel JSON.

MCP

Start the OAuth flow:

{ "provider": "dribbble" }

The tool returns either a URL elicitation (for clients that support it) or:

{
  "connected": false,
  "pending": true,
  "connectionId": "abc123",
  "url": "https://dribbble.com/oauth/authorize?...",
  "message": "A human must open this URL and log in. Then poll with connectionId or check integrationList."
}

Give the URL to a human, then poll:

{ "connectionId": "abc123" }

There is no follow-up step: is_between_steps is false. Call integrationList for the channel id.

Provider functions (triggerTool)

MCP:

{ "integrationId": "int_...", "methodName": "teams" }

The function has an empty input_schema / dataSchema.

The teams result cannot currently be used for posting. The team setting is ignored by post(), and Dribbble requires a numeric team_id field in the shot upload, which the provider never sends. Treat teams as informational only.

Post Settings & Media Validation

settings_schema()

CLI note: the simple rustiz posts create --channel <id> --content "..." form cannot pass provider settings. Use rustiz posts create --json post.json with a CreatePostDto (type, date, posts[].settings, …) when any of these fields are required.

There is no description, tags, low_profile, rebound_source_id or scheduled_for setting. The post body (PostDetails.message) becomes the shot description.

Example object form:

{
  "title": "Dashboard UI — dark mode",
  "team": null
}

MCP settings array:

{
  "settings": [
    { "key": "title", "value": "Dashboard UI — dark mode" }
  ]
}

The engine adds "__type": "dribbble" automatically if missing.

validate_settings() rules

1. title must exist and be a string; it must not be empty.
2. team, if present and not null, must be a string and must parse as a URL.
   • An empty string is not a URL and fails with team must be a URL. This matters because docs.postiz.com examples use "team": "".
   • Use null or omit team for a personal shot.
3. There is no check that the team URL belongs to the authenticated user, and no conversion from a team URL to Dribbble’s numeric team_id.

check_validity() rules

check_validity() is called before scheduling/publishing with each part’s media. It looks only at the first post part:

1. If any item’s path contains "mp4" (case-sensitive), return Does not support mp4 files.
2. Otherwise, the part must have exactly one media item. Zero or two or more returns Requires one item.
3. It reads the image dimensions and accepts only:
   • 400×300, or
   • 800×600. Anything else returns Invalid image size. Requires 400x300 or 800x600 px images.

Because the MP4 check runs before the count check, a two-item list containing an MP4 returns the MP4 message, not Requires one item.

The validation does not check:

• file size (Dribbble’s limit is 8 MB);
• actual file type (Dribbble accepts GIF, JPG or PNG);
• file extension;
• whether the image is animated or has the right color profile.

A 400×300 WebP or a 400×300 20 MB PNG passes Rustiz validation and is then rejected by Dribbble’s API.

Media and publish behavior

• Exactly one media item is used: first.media.first(). All other media is ignored.
• The file is streamed as multipart form data under the field name image, with the original filename and a MIME type inferred from the extension (jpg/jpeg, png, gif, webp, mp4; unknown → no MIME part).
• The form also sends:
  • title from settings.title;
  • description from first.message.
• It does not send team_id, tags, low_profile, rebound_source_id or scheduled_for.
• Dribbble’s API responds 202 Accepted with a Location header such as https://api.dribbble.com/v2/shots/471756. Rustiz treats any 2xx as success, takes the last path segment as the post id, and returns https://dribbble.com/shots/{id}. The shot may return 404 at that URL until Dribbble finishes processing, because creation is asynchronous.
• If the 2xx response has no Location, the post id is empty and the release URL becomes https://dribbble.com/shots/ — a silent bad success.
• A 4xx other than 429 is converted to a bad_body error using the platform message field, or Dribbble rejected the shot with status {status} if there is no message. 429 is passed to the generic retry path.

Plugs

No @Plug or @PostPlug methods. run_plug() and run_post_plug() use the trait defaults and return ProviderError::Unsupported.

Implementation Notes & Gotchas

The refresh path calls Pinterest (upstream bug, faithfully ported)

This is the most important thing to know about dribbble.rs. The module header says it explicitly:

Faithful port note: upstream refreshToken calls the Pinterest sandbox endpoints with PINTEREST_CLIENT_ID / PINTEREST_CLIENT_SECRET. That copy paste bug is kept here.

In refresh_token() (around lines 258–318):

1. It builds Basic auth from PINTEREST_CLIENT_ID and PINTEREST_CLIENT_SECRET.

2. It posts to {PINTEREST_BASE_URL}/v5/oauth/token, default https://api-sandbox.pinterest.com/v5/oauth/token.

3. The form contains grant_type=refresh_token, the Dribbble refresh token, scope=public,upload, and a redirect_uri of:

   {FRONTEND_URL}/integrations/social/pinterest
   

   That is pinterest, not dribbble — line 283 of dribbble.rs.

4. It then calls {PINTEREST_BASE_URL}/v5/user_account with the returned token and returns a AuthTokenDetails whose id, name, username and picture are Pinterest account fields.

Consequences:

• A Dribbble refresh will fail unless Pinterest sandbox credentials are also configured, and it will send the Dribbble refresh token to Pinterest.
• Even if it succeeds, the token is a Pinterest token and the returned identity is a Pinterest user; it cannot be used to post to Dribbble.
• PINTEREST_CLIENT_ID / PINTEREST_CLIENT_SECRET are not declared in required_env(), so the deployment’s provider status will not warn about them.
• Normal Dribbble operation tries to avoid refresh: authenticate() sets expires_in: Some(999999999) (about 31.7 years) and refresh_token: Some(""). Dribbble’s token response does not document a refresh token. A 401 still enters the refresh path, where this bug fires.
• Workaround: do not rely on token refresh. If a Dribbble channel is marked refresh-needed or starts returning 401, reconnect it through rustiz channels connect dribbble rather than trying to repair the token.

Other gotchas

• The team setting is dead code. It is in the schema and validated, but post() never reads it. Dribbble’s create-shot API wants a numeric team_id; the teams tool returns numeric ids, but there is no path from the setting to the request. Team shots cannot be published by this provider.

• "team": "" fails validation. The docs examples use an empty string, but is_url("") is false, so the call fails with team must be a URL. Omit the key or send null.

• The token exchange query is hand-built and unencoded. authenticate() constructs:

  POST {DRIBBBLE_OAUTH_BASE_URL}/oauth/token?client_id=...&client_secret=...&code=...&redirect_uri=...
  

  The authorization code and redirect URI are not URL-encoded. Dribbble authorization codes are normally URL-safe and the redirect URI has no query string, so this usually works, but a client secret or code containing &, # or + would break the request.

• expires_in is synthetic. Dribbble’s OAuth token response contains access_token, token_type and scope, but no expires_in. Rustiz stores 999999999 seconds so the engine will not try to refresh. This is a deliberate workaround, not data from Dribbble.

• No refresh token is stored. authenticate() sets refresh_token: Some(""). Any engine refresh attempt passes an empty string to the Pinterest bug. There is no way to recover a Dribbble token through this provider.

• analytics flags are misleading. info.supports_analytics and info.supports_post_analytics are true, so generic callers may ask for analytics, but both methods return Ok(vec![]). Dribbble does not expose detailed shot analytics through this API.

• Creation is asynchronous. Dribbble returns 202 + Location; the shot may 404 for a short time while it is processed. Rustiz marks the post Completed immediately. A later analytics/post lookup at the returned https://dribbble.com/shots/{id} may briefly fail.

• Missing Location is a silent empty success. The code does not treat a 2xx without Location as an error; it returns an empty post id and https://dribbble.com/shots/. Check the response if a Dribbble post appears successful with no URL.

• Rate limits are per authenticated user. 60 requests/minute and 1,440/day. max_concurrent_job = 3 keeps concurrency low, but retries and multiple channels on one account share the limit. 429 is retried by the generic HTTP layer up to three times; there is no provider-specific handle_errors() mapping.

• Validation is dimensions-only. See the media section: size, MIME and extension are unchecked. Use 800×600 PNG/JPG under 8 MB for the most reliable result.

• Description is plain text. The editor is normal, so HTML is stripped before message reaches Dribbble. Tags are not sent; put hashtags in the description if desired.

• The release URL is constructed, not read from Dribbble. It is always https://dribbble.com/shots/{id}; Dribbble’s html_url field is not used.

References

• Dribbble OAuth documentation (authorize/token, redirect rules, scopes, errors): https://developer.dribbble.com/v2/oauth/
• Dribbble create-shot documentation (400×300 or 800×600, 8 MB, GIF/JPG/PNG, video unsupported, 202 + Location, team_id, rate limits): https://developer.dribbble.com/v2/shots/
• Dribbble API overview and rate limits: https://developer.dribbble.com/v2/
• Dribbble application registration: https://dribbble.com/account/applications/new
• Postiz Dribbble self-host guide (contains the DRIBBLE_* / dribble typos — use the Rust names instead): https://docs.postiz.com/self-host/providers/dribbble
• Postiz provider settings (note the "team": "" example, which Rustiz rejects): https://docs.postiz.com/public-api/providers/dribbble
• Postiz posting rules: https://docs.postiz.com/general/platforms/overview

Facebook Page (facebook)

Facebook Page publishing uses the Meta Graph API with a Facebook Login for Business token. Rustiz stores the user’s long-lived token at connect time, then the is_between_steps setup step exchanges it for a Page access token for the chosen Page. All publishing happens as the Page, never as the personal profile.

• Rust source: crates/rustiz-providers/src/facebook.rs
• Upstream port: facebook.provider.ts
• Editor: Normal
• Connection mode: oauth (Facebook Login for Business)
• Related providers: instagram and instagram-standalone share the same Meta app family, but only instagram reuses FACEBOOK_APP_ID / FACEBOOK_APP_SECRET

Overview

Server Environment Variables

required_env() returns exactly:

#![allow(unused)]
fn main() {
fn required_env(&self) -> &'static [&'static str] {
    &["FACEBOOK_APP_ID", "FACEBOOK_APP_SECRET"]
}
}

required_env_alternatives() is not overridden.

rustiz providers --status checks only that FACEBOOK_APP_ID and FACEBOOK_APP_SECRET are non-empty. It does not verify the app mode, the registered redirect URI, or that the app has the Page permissions.

Step-by-Step Developer App Setup

Facebook Page and Instagram (Facebook Business) can share one Meta app. If you already followed instagram, skip the app creation and reuse the same credentials.

1. Create the Meta app

1. Sign in at https://developers.facebook.com/apps/creation/.
2. Choose Other → Business as the app type. A Business portfolio is strongly recommended; public apps need Business Verification.
3. Enter the app name, contact email and (optionally) a Business portfolio.
4. In the App Dashboard, add the product Facebook Login for Business.
5. Open Facebook Login for Business → Settings and add the exact Valid OAuth Redirect URI from step 2.

2. Redirect URI (exact)

Facebook::redirect_uri(None) is:

#![allow(unused)]
fn main() {
format!("{}/integrations/social/facebook", self.ctx.config.frontend_url())
}

Examples:

https://social.example.com/integrations/social/facebook   # production
http://localhost:5000/integrations/social/facebook        # Docker / rustiz serve
http://localhost:4200/integrations/social/facebook        # upstream Postiz dev UI

There is no redirectmeto.com wrapper and no trailing slash. Facebook matches the URI exactly, including scheme, host, path and any query string.

Reconnect quirk: when the OAuth start is called with ?refresh=<channel id>, authenticate() sends …/integrations/social/facebook?refresh=<id> as the redirect_uri in the token exchange, while the login dialog itself used the URI without the query. If Meta rejects the exchange with a redirect-URI mismatch, reconnect by starting a fresh connection instead of using the refresh link. Also see the page-id comparison note in the gotchas.

3. Permissions requested and checked

Facebook::scopes() returns, in this order:

#![allow(unused)]
fn main() {
vec![
    "pages_show_list",
    "business_management",
    "pages_manage_posts",
    "pages_manage_engagement",
    "pages_read_engagement",
    "read_insights",
]
}

They are joined with commas in the login URL. After the token exchange, authenticate() calls:

GET /v25.0/me/permissions?access_token=…

and collects every entry whose status is "granted", then calls check_scopes() with the comma-joined list. All six must be granted or the connect fails with NotEnoughScopes. Users can decline individual Page permissions in the login dialog, so this is a common failure.

Missing publish_video: Meta’s Pages API documentation lists publish_video as a permission needed “if you are publishing a video to the Page”. The Rust provider does not request it. Video posts can therefore fail with (#100) No permission to publish the video, which handle_errors already maps to a friendly message. Add publish_video to the app’s requested permissions and re-authorize if you need video.

4. Page tasks and Business Manager

The app user must be able to perform the Page tasks CREATE_CONTENT, MANAGE and MODERATE on the target Page. In practice:

• The user must be a Page admin or have full control.
• If the Page belongs to a Business portfolio, the user must have the Page assigned in Business Manager.
• The Page must be published; an unpublished Page cannot be posted to.
• A Page that requires Page Publishing Authorization (PPA) must complete it before API publishing works.

pages() tries both sources:

1. GET /v25.0/me/accounts?fields=id,username,name,access_token,picture.type(large)&limit=100
2. GET /v25.0/me/businesses, then owned_pages and client_pages for each business, following paging.next.

Pages are deduplicated by id. A Page discovered through Business Manager but without a Page token is treated as “no permission” and produces the message “Your Facebook user has no permission to manage this page. Ask a page admin for full content access, then reconnect the channel.”

5. App roles and Development mode

• Development mode (all new apps): only users with a role on the app (Admin, Developer, Tester) can grant permissions and see content published by the app. This is the normal setup for a single-user/self-hosted install.
• Add testers under App roles → Roles → Testers. They must accept the invitation before they can log in.
• In Development mode, posts with media are visible only to app role users; other people see the post without the image. This is the single most common “my image is missing” report in the Postiz docs.
• Data created in Development mode becomes visible to everyone after switching to Live.

6. Live mode and App Review

Switch the app to Live only after development is complete.

• Live mode can request permissions from anyone, but only permissions approved through App Review.
• Advanced Access for pages_manage_posts, pages_manage_engagement, pages_read_engagement, pages_show_list, business_management and read_insights requires App Review and Business Verification.
• For an app used only by its owner and role users, Standard Access in Development mode is enough; no App Review is required.
• App Review submissions need a screencast showing the complete Facebook login, the Page selection, and a real post published as the Page. Missing or vague use-case descriptions are a common rejection reason.
• Permissions unused for 90 days may expire and must be re-granted.

7. Testing checklist

1. GET /v25.0/me/accounts returns the Page with a non-empty access_token.
2. GET /v25.0/{page-id}?fields=name,fan_count works with that token.
3. A text-only POST /{page-id}/feed succeeds.
4. A photo post succeeds (JPEG/PNG < 4 MB).
5. A video post succeeds only if publish_video (or the equivalent Page task) is granted.
6. A story appears in the Page’s story tray and disappears after 24 hours.

There is no Facebook sandbox environment for Pages. Test against a real test Page and a test app in Development mode.

Connecting a Channel (CLI & MCP)

CLI

rustiz channels connect facebook
rustiz channels connect facebook --open
rustiz channels connect facebook --timeout 600

The CLI prints the login URL to stderr and, when FRONTEND_URL points at this machine, serves the callback and waits for the channel to appear. With a remote FRONTEND_URL it prints the URL and exits; the server handles the callback.

The OAuth callback creates the channel with inBetweenSteps = true. The CLI has no setup command: finish the Page selection with the MCP channelSetupTool (or the corresponding web UI). Until then the channel exists but cannot publish; the scheduler refuses it with “channel … is not set up yet, finish it with channelSetupTool”.

MCP connectChannelTool

{ "provider": "facebook" }

Typical response:

{
  "connected": false,
  "pending": true,
  "connectionId": "…",
  "url": "https://www.facebook.com/v25.0/dialog/oauth?client_id=…&redirect_uri=…&state=…&scope=pages_show_list,business_management,pages_manage_posts,pages_manage_engagement,pages_read_engagement,read_insights",
  "message": "A human must open this URL and log in. Then poll with connectionId or check integrationList."
}

Poll with:

{ "connectionId": "…" }

After the callback, integrationList shows the channel with "inBetweenSteps": true.

Finishing setup: triggerTool then channelSetupTool

1. List the Pages the token can publish to:

   {
     "integrationId": "<unfinished channel id>",
     "methodName": "pages",
     "dataSchema": []
   }
   

   facebook exposes one function:

   {
     "name": "pages",
     "description": "Pages the connected account can publish to",
     "input_schema": { "type": "object", "properties": {} }
   }
   

   The result is the same array pages() builds: [{id, username, name, access_token, picture:{data:{url}}}, …].

2. Choose a Page and call:

   {
     "integrationId": "<unfinished channel id>",
     "data": { "page": "<page id>" }
   }
   

   channelSetupTool calls Facebook::fetch_page_information(token, {"page": "<id>"}), which re-reads /me/accounts and Business Manager, then finish_integration_setup replaces the channel’s internalId, name, picture, profile and token with the Page values and clears inBetweenSteps.

3. Verify with integrationList: the channel name is now the Page name and inBetweenSteps is false.

There is exactly one data key for Facebook: page. Do not send {"id": …} (that is the Instagram shape) or {"pageId": …}.

What not to send

• customFields routes to connect_custom() and treats the object as an OAuth authorization code. Never send it to facebook.
• externalUrl is not used by Facebook; it is ignored by connect.rs (only mastodon-custom requires it).

Post Settings & Media Validation

settings_schema()

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link to attach as a preview card (image, title, domain), used only for text posts without media. A URL inside the content alone shows as plain text with no card"
    },
    "post_type": {
      "type": "string",
      "enum": ["post", "story"],
      "description": "Publish a regular page post or a story. Stories need at least one photo or video attachment, and each media becomes a separate story."
    },
    "text_format_preset_id": {
      "type": "string",
      "description": "Optional Facebook background preset for text-only posts (max ~130 characters)."
    },
    "title": {
      "type": "string",
      "description": "Title of the video, used only for video (non-story) posts"
    }
  },
  "additionalProperties": true
}

additionalProperties: true — unknown keys are accepted and ignored. This is intentional for forward compatibility.

validate_settings()

• settings must be an object.
• post_type, when non-null, must be exactly post or story.
• text_format_preset_id, when non-null, must be a string.
• title, when non-null, must be a string.
• url, when non-null, must be a string. An empty string is allowed and means “no link”. A non-empty value must be a web URL: either a full http(s) URL or a scheme-less host containing a dot (the code retries with https:// prefixed). example.com/x is accepted; not a url is not.
• No length or presence checks are performed here. Facebook itself enforces the 63,206-character limit and the 130-character preset limit.

check_validity()

Only stories are checked:

if post_type == "story" and the first post has no media:
    "Story should have at least one media"

There is no check for:

• maximum 10 photos per feed post (Facebook’s own limit);
• video duration/size;
• photo dimensions or 4 MB size limit;
• mixing photos and video in one feed post.

Those fail at the Graph API and are mapped by handle_errors().

Media requirements

Important details:

• Everything is URL-based. Rustiz never uploads bytes to Facebook; it gives Meta a URL and Meta fetches it. The media must be on a public HTTPS server at publish time. A Rustiz install behind a private network needs a public UPLOAD_DIRECTORY/CDN or a tunnel.
• Stories are one story per media item. story_pending() uploads every attachment, then finalize_post() publishes exactly one item per call. A two-photo story produces two separate stories.
• Video detection is .mp4 only. has_extension(video_path, "mp4") looks for the substring .mp4 anywhere in the path (case-insensitive). A .mov file takes the photo path and fails.
• Feed video release URL is always a Reel URL. The video branch returns https://www.facebook.com/reel/{video_id} and ignores the permalink_url that the API returns. A normal Page video is not necessarily a Reel; use the API response if you need the canonical link.
• Alt text is ignored. MediaContent.alt is never sent to Facebook.
• A feed post with both link and media may be ignored or rejected. The code sends link even when attached_media is present. The schema says url is for text posts without media; treat that as the supported path.

Threads

supports_comments = true. A multi-entry post works as follows:

1. The first entry is published as a feed post, photo post, video post or story.
2. Each later entry is published by comment() against the previous post id (or the root post id for the first comment).
3. comment() sends message plus, if the comment has media, the first media item as attachment_url.
4. Comments are Page comments (POST /{post-id}/comments), so they appear under the post in Facebook’s comment UI, not as separate feed posts.

For stories, comments target the story post_id; Facebook’s story comments are limited and may not appear in all clients.

Plugs

facebook.rs has no @Plug or @PostPlug methods. run_plug() and run_post_plug() use the trait defaults and return ProviderError::Unsupported. The pages helper is a dashboard function, not a plug.

Implementation Notes & Gotchas

• The channel is unusable until setup is finished. authenticate() stores a user token and a user id. Only channelSetupTool swaps in the Page token and Page id. Publishing before setup posts as the user and fails with “Unpublished posts must be posted to a page as the page itself”, which is mapped to a refresh error telling you to reconnect.
• Page token lifecycle. The initial long-lived user token is valid about 60 days; expires_in is hard-coded to 59 * 24 * 3600. refresh_token() is a no-op (returns an empty access token with expires_in: 0), and refresh_cron is false. There is no proactive refresh. When the token expires, publishing gets a 190/Error validating access token, the engine marks the channel refreshNeeded, and the user must reconnect. Page tokens derived from a long-lived user token can outlive the user token for Page actions, but Rustiz still gates on the stored expiration.
• Reconnect page-id mismatch. save() with ?refresh=<id> requires the re-authenticated AuthTokenDetails.id to equal the stored integration.internal_id. For a Page channel that stored id is the Page id, while authenticate() returns /me’s user id. The comparison fails with “Please refresh the channel that needs to be refreshed”. The provider’s reconnect() (which re-derives the Page token) is only called by the engine when root_internal_id is set, and Facebook channels have no root. Practically: reconnect by creating a new connection, then delete the old channel.
• refresh_token is not a refresh token. authenticate() stores the long-lived access token in both access_token and refresh_token. Nothing rotates it. Do not treat it as a Meta fb_exchange_token input.
• Long-lived exchange has no redirect URI. The second token call is GET /oauth/access_token?grant_type=fb_exchange_token&client_id=…&client_secret=…&fb_exchange_token=…&fields=access_token,expires_in. Meta ignores fields here; the code reads access_token only.
• Graph version is pinned to v25.0. Meta supports each Graph version for roughly two years. Check the App Dashboard’s “API version” notice before a long-lived deployment; upgrading requires editing the constant.
• Business Manager failures are swallowed. pages() and fetch_page_information() ignore errors from /me/businesses, owned_pages and client_pages and continue with /me/accounts. A permission error on Business Manager therefore shows up as “Page not found in your accounts”, not as a Graph error.
• found_without_token matters. A Page listed through a business the user has no role on comes back without access_token. The provider detects this and returns a specific message instead of a generic “not found”.
• max_concurrent_job = 500 is optimistic. Meta rate limits are per app/user pair and Pages have their own publishing limits. A 500-job burst can hit (#32) Page request limit or 1366046/1390008 throttling. The code maps 1390008 to a retry (“You are posting too fast, please slow down”).
• Feed posts are not pending. post_pending() for post_type != story calls post_non_story(), which performs the feed call and returns PostStatus::Success. supports_pending = true exists only for the story flow. The engine’s post() compatibility path still loops on the story pending data; ordinary posts return immediately.
• Story handshake. Story publishing uses attempting (the item index) and confirmed. check_post_status() waits for every not-yet-published video to report upload_complete or ready, then witnesses the armed item. If a run dies after the confirm, the provider refuses to retry with “Facebook may have already published part of the story” rather than duplicate a story.
• One story per call. finalize_post() publishes items[published_count], increments the counter and returns Pending if more items remain. Each story counts as a separate publication and has its own post_id.
• Video processing is polled by GET /{video_id}?fields=status. Only upload_complete and ready count as done; error becomes “Video processing failed”. There is no byte-level upload progress because the file is fetched by Meta from a URL.
• Comment media is a URL attachment. attachment_url makes Facebook scrape the URL as a link preview. It does not upload the image as a comment photo. A comment with a video URL is unlikely to render as a video.
• Analytics swallow failures. analytics() logs and returns an error only when the insights response contains an error object; post_analytics() catches feed errors and returns []. Video insights are used whenever the post id has no underscore:
  • feed post id {pageid}_{postid} → /insights;
  • Reel/video id (bare numeric) → /video_insights. A Page post id that happens to lack an underscore is misclassified as video.
• Percentage change is fake. Page analytics hard-code percentage_change: 5.0; post analytics hard-code 0.0. Do not present these as real period-over-period changes.
• Insight metric names are version-sensitive. page_total_media_view_unique and page_media_view have been renamed/deprecated by Meta over time. If the insights call returns an error, the whole analytics request fails (page analytics) or returns empty (post analytics).
• text_format_preset_id retry. is_preset_rejection() treats an error as a preset rejection unless the detail mentions access token, re-authenticate, revoked, code 190, or the message is not “Unknown Error”. It then retries once without the preset. This can mask a real error as a successful plain post.
• Preset length is UTF-16. message.encode_utf16().count() <= 130 matches JavaScript string length, not Unicode scalar count. An emoji counts as 2.
• Error mapping. Dozens of Meta subcodes are translated: 1366046 photos

  4 MB / not JPG-PNG, 1390008 posting too fast, 1346003 abusive content, 1404006 security check, 1404078 Page publishing authorization, 1366051 duplicate photos, 1609008 Facebook.com links, 4854002 identity confirmation, subcode 459 security check, subcode 492 lost Page role, subcode 33 deleted Page/post. A bare 401 is treated as an unknown error, not a refresh.

• pages() exposes Page access tokens. The pages function returns the raw access_token for every Page, and triggerTool sends that array to the MCP client. Treat the tool output as secret; do not log it or paste it into shared transcripts. The channelSetupTool response itself only returns {success, name}.
• Rate limits. Meta Graph API limits are per app/user pair and depend on Page impressions; Pages also have daily posting limits. max_concurrent_job = 500 should be lowered for media-heavy workloads. The provider does not read X-Business-Use-Case-Usage or X-App-Usage headers to back off.
• No sandbox. There is no Facebook Pages sandbox. Use a test Page, a test app in Development mode, and role users. Switching the app to Live exposes Development-mode content to everyone.

References

• Meta app creation: https://developers.facebook.com/apps/creation/
• Facebook Login for Business: https://developers.facebook.com/docs/facebook-login/facebook-login-for-business
• Permissions reference: https://developers.facebook.com/docs/permissions/reference
• App modes (Development vs Live): https://developers.facebook.com/docs/development/build-and-test/app-modes
• Access levels (Standard vs Advanced): https://developers.facebook.com/docs/graph-api/overview/access-levels
• App Review: https://developers.facebook.com/docs/app-review
• Access tokens (user, Page, long-lived): https://developers.facebook.com/docs/facebook-login/guides/access-tokens
• Pages API posts: https://developers.facebook.com/docs/pages-api/posts
• Page Stories API: https://developers.facebook.com/docs/page-stories-api
• Page Insights: https://developers.facebook.com/docs/graph-api/reference/page/insights
• Postiz Facebook setup: https://docs.postiz.com/providers/facebook
• Postiz Facebook settings: https://docs.postiz.com/public-api/providers/facebook

Farcaster / Warpcast (wrapcast)

Farcaster is a decentralized social protocol; Warpcast is its best-known client. Rustiz publishes through Neynar, which manages the Farcaster signer. The connect flow is not OAuth: the server creates a Neynar signer, signs a SignedKeyRequest with the app’s custody mnemonic, shows the human an approval link/QR code, and polls until the signer is approved in the Farcaster app.

• Rust source: crates/rustiz-providers/src/farcaster.rs
• Upstream port: farcaster.provider.ts
• Editor: Normal
• Connection mode: signer
• Identifier is wrapcast, not farcaster.

Overview

Server Environment Variables

required_env() returns four variables:

#![allow(unused)]
fn main() {
&[
    "NEYNAR_CLIENT_ID",
    "NEYNAR_APP_FID",
    "NEYNAR_APP_MNEMONIC",
    "NEYNAR_SECRET_KEY",
]
}

required_env_alternatives() is not overridden.

rustiz providers --status requires all four variables and reports wrapcast as missing until they are set. NEYNAR_CLIENT_ID is required by that check even though the headless flow does not use it; set any non-empty value if your Neynar app does not expose one (for example, the client id shown in the dashboard).

The fallback API key inside api_key() is the placeholder 00000000-000-0000-000-000000000000. It is only used when NEYNAR_SECRET_KEY is unset, which provider_status() normally prevents.

Step-by-Step Developer App Setup

1. Create a Neynar account and app

1. Sign in at https://dev.neynar.com.
2. Create an app. Neynar returns a Client ID and a Secret Key. The secret key is the API key used for every /v2/farcaster/... call.
3. Note the app’s FID and the custody mnemonic of the Farcaster account used as the app. Neynar’s app settings expose the FID; the mnemonic is the seed phrase of that FID’s custody address. If the FID was created in another wallet, use that wallet’s mnemonic instead. The mnemonic is used only to sign signer requests; it is not a user mnemonic.
4. Put the values in the environment:

NEYNAR_CLIENT_ID="…"
NEYNAR_APP_FID="12345"
NEYNAR_APP_MNEMONIC="word word word …"
NEYNAR_SECRET_KEY="…"

5. Restart rustiz serve, rustiz worker and rustiz mcp; they read the configuration at startup.

2. What the app FID and mnemonic are for

Farcaster requires an app to prove it controls an FID before a signer can be registered for a user. Rustiz derives the app’s Ethereum key from the mnemonic at m/44'/60'/0'/0/0 (BIP-39 seed, empty passphrase, BIP-32) and signs the EIP-712 payload:

Domain:
  name:              "Farcaster SignedKeyRequestValidator"
  version:           "1"
  chainId:           10
  verifyingContract: 0x00000000FC700472606eD4Fa22623AcF62c60553

Type:
  SignedKeyRequest(uint256 requestFid, bytes key, uint256 deadline)

The signature is 65 bytes (r, s, v+27), 0x-prefixed. If the mnemonic is wrong, Neynar rejects the signed-key registration with a 4xx; the connect call fails before a human sees an approval link.

The implementation is a small self-contained BIP-39/BIP-32 + secp256k1 + Keccak-256 signer; it does not use viem or an Ethereum SDK.

3. Redirect URI

There is no redirect URI. start_farcaster() in crates/rustiz-server/src/connect.rs never calls generate_auth_url(). The human approval is a deep link into the Farcaster app:

farcaster://signed-key-request?token=0x…

The provider also renders the link as a PNG QR data URL. No domain, no FRONTEND_URL callback and no redirectmeto.com are involved.

4. Scopes

Farcaster/Neynar does not use OAuth scopes here. info.scopes is empty. check_scopes() is never called. Access is controlled by the Neynar API key and the approved signer’s permissions.

5. Sandbox / testing vs production

There is no Farcaster “sandbox” and no app review. The gates are:

• Signer approval. Every user must approve the signer once in the Farcaster app. That is an onchain transaction; Neynar charges for it (or the developer sponsors it with NEYNAR_SPONSOR_SIGNERS=true and pays in credits). Neynar’s own documentation warns: “While testing please reuse the signer, it costs money to approve a signer.”
• Neynar plan/credits. Read and write endpoints are metered by the Neynar plan. A free/dev plan is enough to test with a few accounts; production volume needs a paid plan.
• App FID. A production app should use a dedicated Farcaster account/FID for the app, not a personal account, because the custody mnemonic signs every signer request.

For tests:

1. Connect once with a test Farcaster account and keep the resulting channel.
2. Do not delete/reconnect repeatedly: each connect attempt creates a new signer and can cost another approval.
3. If you already have an approved Neynar signer, skip signer creation with customFields.signerUuid (see below).

Connecting a Channel (CLI & MCP)

Flow A — create a new signer (normal)

CLI

rustiz channels connect wrapcast

The command prints a JSON document (stdout) with:

{
  "connected": false,
  "pending": true,
  "connectionId": "fc_…",
  "approvalUrl": "farcaster://signed-key-request?token=0x…",
  "qrCode": "data:image/png;base64,…",
  "message": "Give this link (or QR code) to the human: …"
}

The CLI does not wait for the approval, because there is no browser callback. Give the approvalUrl or qrCode to the human, then poll:

rustiz channels connect-status fc_…

The connection id lives for 30 minutes. Polling does not extend the TTL; if it expires, start again (and pay for a new signer).

MCP connectChannelTool

{ "provider": "wrapcast" }

Returns the same connectionId, approvalUrl and qrCode. Poll with:

{ "connectionId": "fc_…" }

integrationSchema reports:

{
  "type": "signer",
  "headless": true,
  "requiresHuman": true,
  "requires": [
    "NEYNAR_CLIENT_ID",
    "NEYNAR_APP_FID",
    "NEYNAR_APP_MNEMONIC",
    "NEYNAR_SECRET_KEY"
  ]
}

Flow B — reuse an approved signer (customFields.signerUuid)

If a Neynar signer was already created and approved (for example, by another Neynar app using the same API key), pass its uuid:

{
  "provider": "wrapcast",
  "customFields": {
    "signerUuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec"
  }
}

CLI:

printf '%s' '{"signerUuid":"19d0c5fd-9b33-4a48-a0e2-bc7b0555baec"}' \
  | rustiz channels connect wrapcast --fields -

The server:

1. Requires NEYNAR_SECRET_KEY.
2. Calls GET /v2/farcaster/signer?signer_uuid=….
3. If the status is approved and the response has an fid, builds the same base64 user payload and connects immediately.
4. If the signer is not approved, returns an actionable error such as That Farcaster signer is not approved yet (status: pending_approval). Open its approval link in the Farcaster app first.

This path only checks NEYNAR_SECRET_KEY. It does not need NEYNAR_APP_FID, NEYNAR_APP_MNEMONIC or NEYNAR_CLIENT_ID at runtime. The normal signer-creation path calls provider_status() and requires all four, so in practice set all four.

Signer approval details

The server’s sequence (Farcaster::create_signer()):

1. POST /v2/farcaster/signer with {} → signer_uuid, public_key, status: generated.
2. deadline = now + 24 hours.
3. Sign the EIP-712 SignedKeyRequest with the app mnemonic.
4. POST /v2/farcaster/signer/signed_key with:

{
  "signer_uuid": "…",
  "app_fid": 12345,
  "deadline": 1760000000,
  "signature": "0x…",
  "sponsor": { "sponsored_by_neynar": true }
}

sponsor is present only when NEYNAR_SPONSOR_SIGNERS=true.

5. Read signer_approval_url and signer_uuid; build qrCode = qr_data_url(approval_url) (PNG data URL, 4 px modules, 4-module margin).
6. Store {signerUuid, approvalUrl} in the oauth_states row as code_verifier, provider="wrapcast", TTL 30 minutes.

When the human approves in the Farcaster app, the server polls:

1. GET /v2/farcaster/signer?signer_uuid=….
2. If status != "approved", return pending (or an error if revoked).
3. If approved, read fid.
4. GET /v2/farcaster/user/bulk?fids=<fid> to get username, display_name, pfp_url.
5. Build a base64 JSON payload:

{
  "signer_uuid": "…",
  "fid": 12345,
  "username": "alice",
  "display_name": "Alice",
  "pfp_url": "https://…"
}

6. authenticate() decodes it and stores:
   • id = FID
   • access_token = signer_uuid
   • refresh_token = ""
   • expires_in = 200 years
   • username = Farcaster username
   • name = display name
   • picture = pfp URL

The signer uuid is the credential used for every cast. There is no token refresh.

Do not send customFields without signerUuid

connect.rs treats any customFields object as the credential path. For wrapcast, the object must contain signerUuid (or signer_uuid); otherwise the flow returns Farcaster customFields needs signerUuid of an already-approved Neynar signer.

Post Settings & Media Validation

settings_schema()

The field is named subreddit for historical reasons (copied from Reddit), but it holds Farcaster channels:

{
  "type": "object",
  "properties": {
    "subreddit": {
      "type": "array",
      "description": "Farcaster channels to cast into (from the subreddits tool). Leave empty to cast on the user's timeline.",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "description": "Channel id." }
            },
            "required": ["id"],
            "additionalProperties": true
          }
        },
        "required": ["value"],
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

There is no required at the top level. subreddit may be omitted, null or an empty array; all three mean “post to the user’s timeline”.

validate_settings() rules

1. If subreddit is present and not null, it must be an array.
2. Each entry must be an object.
3. Each entry must have a value that is an object.
4. value.id must be a string.
5. Extra properties are allowed at every level.

It does not check that the channel exists, that the id is non-empty, or that the user can post in it. Neynar returns the error at publish time.

check_validity()

Only one rule:

#![allow(unused)]
fn main() {
if posts.iter().any(|items| {
    items.iter().any(|item| item.path.contains("mp4"))
}) {
    return Ok(Some("Can only accept images".into()));
}
}

• Any media path containing mp4 (case-sensitive) rejects the whole post.
• No check on image count, size, format or URL reachability.
• The check runs for every entry in the thread, even though threads are effectively disabled (supports_comments = false).

Media requirements

Farcaster casts support up to 2 embeds, each a URL up to 256 bytes. Rustiz does not upload media: it maps every MediaContent.path to:

{ "url": "https://cdn.example/image.png" }

and sends them in embeds to POST /v2/farcaster/cast. Consequences:

• The URL must already be publicly reachable; a local file path will not work.
• Rustiz does not cap embeds at 2. Three or more media items produces a request Neynar/Farcaster rejects.
• Alt text, thumbnails and video are ignored.
• Images are the only supported type; check_validity() blocks .mp4, but a .MP4 (uppercase) bypasses it and is sent as a URL embed.
• A cast can have text plus embeds; an empty text with embeds may be accepted, but Rustiz always sends text (possibly empty).

Channels

• cast_ids() reads posts.first().settings["subreddit"].
• null, a non-array, or an empty array → one cast with no channel_id (timeline).
• A non-empty array → one cast per value.id, each with channel_id.
• post_id and release_url are comma-joined across channels. The engine stores the whole string; comment() splits it on commas to reply to every cast.
• If one channel cast fails, the whole post() returns an error. Casts already published to earlier channels remain live; there is no rollback.
• The same applies to replies: comment() sends one reply per parent id and stops at the first failure.

Plugs

No @Plug / @PostPlug methods. run_plug() and run_post_plug() return Unsupported.

triggerTool: channel search

functions() declares one function:

MCP:

{
  "integrationId": "int_…",
  "methodName": "subreddits",
  "dataSchema": [{ "key": "word", "value": "developers" }]
}

Use the returned id as subreddit[].value.id. There is no channelSetupTool: is_between_steps is false, so the channel is selected per post, not at connect time.

Implementation Notes & Gotchas

• Threads are implemented but not advertised. comment() is a full implementation (reply to each parent cast with optional embeds), yet info.supports_comments is never set to true. The engine truncates a multi-entry post to the first entry, and MCP validatePostTool reports “Farcaster does not support thread replies”. If you need threads, set info.supports_comments = true in Farcaster::new(); the code path already exists.
• post() only reads the first PostDetails. Even if called directly with several entries, it publishes one cast per configured channel for the first entry and ignores the rest. The engine truncates the chain first because supports_comments = false.
• NEYNAR_CLIENT_ID is dead weight in the headless flow. It is required by provider_status() and only used by generate_auth_url(), which returns "{client_id}||{state}" — not a URL and never called by connect.rs. Set it, but do not expect it to affect signer creation.
• Neynar header mismatch. The Rust code sends the API key as api_key. Current Neynar OpenAPI documents the security scheme as x-api-key. Neynar has historically accepted api_key; if every call returns 401, change the header to x-api-key in neynar_get() / neynar_post().
• Trailing slashes. The code uses /v2/farcaster/signer and /v2/farcaster/signer/signed_key without a trailing slash. Neynar’s docs show /v2/farcaster/signer/ and /v2/farcaster/signer/signed_key/. Most gateways normalize this; a 404 on signer creation is the symptom.
• Signer creation is costly and not deduplicated. Every connect attempt calls POST /v2/farcaster/signer and registers a new signed key. There is no lookup of an existing signer before creating one. Reconnecting a channel therefore costs another approval unless you use customFields.signerUuid. Neynar explicitly warns to reuse signers while testing.
• Approval TTL is 30 minutes and is not refreshed. poll_farcaster() does not call put_pending() again, unlike Telegram. If the human misses the window, the state row is gone and a retry starts a new signer.
• create_signer() does not validate Neynar’s response. It reads signer_uuid and signer_approval_url with unwrap_or_default(). A malformed/partial response produces a pending connection with an empty approval URL (and a QR code for an empty string) or an empty signer uuid that can never be polled. Check the raw Neynar response if the first connect call looks wrong.
• signer_status() can get stuck. It only returns an approval code when status == "approved" and the response contains fid. If Neynar reports approved without fid (rare, e.g. partial indexing), the server keeps returning {status:"approved", code:null} and the connect poll never completes. Restarting the connection is the only recovery.
• Revoked signers. poll_farcaster() detects status == "revoked", deletes the pending state and returns an actionable error. The customFields shortcut does not special-case revoked; it says “not approved yet”.
• Rate limits are plan-based. Neynar’s published tiers are roughly: Free (limited), Starter 300 RPM / 5 RPS per endpoint with a 500 RPM global cap, Growth 600 RPM / 10 RPS with 1,000 RPM global, Scale 1,200 RPM / 20 RPS with 2,000 RPM global. max_concurrent_job = 3 is conservative but does not reserve credits. Signer writes and active signers consume credits on top of request limits.
• No signer refresh. refresh_token() returns an empty token with expires_in: 0; the signer uuid is the long-lived credential. If the user revokes the signer in the Farcaster app, the next cast fails with Neynar’s error and the channel must be reconnected with a new signer (or a different approved signerUuid).
• No idempotency. POST /v2/farcaster/cast is called without Neynar’s idem field. A retry after a timeout can double-cast. The engine’s retry policy is the only protection.
• 800 characters is a Postiz limit, not a protocol limit. Farcaster casts are limited by bytes (historically 320 bytes, now 1,024 bytes for standard casts), not by a flat 800 characters. The engine counts chars(); a cast of 800 emoji can exceed the byte limit, and a cast of 800 ASCII characters may be fine. There is no byte check.
• No byte/embed validation. Each embed max 256 bytes and max 2 embeds are Farcaster rules; Rustiz checks neither. A long image URL or a third image fails at Neynar.
• Media is not uploaded. embeds are URLs, so the media must be hosted publicly before publishing. This differs from Bluesky/Mastodon, where Rustiz uploads bytes.
• subreddits is a search, not a list. It returns at most 10 channels for the query. There is no “my channels” call. If the user does not know the channel name, they must search for it.
• is_web3 = true. connect.rs special-cases wrapcast before the generic web3 rejection, so it is supported. Other web3 providers are not.
• No analytics / mentions. supports_analytics, supports_post_analytics and supports_mentions are all false; there are no overrides.
• Release URL. cast_urls() builds https://warpcast.com/{author username}/{cast hash} from the Neynar response. If the response omits the author username, the URL contains //; the hash is still the post id.
• Multiple channels produce comma-joined ids. Any consumer that expects a single cast hash must split on commas. The engine’s comment() already does.

References

• Neynar dashboard: https://dev.neynar.com
• Managed signers overview: https://docs.neynar.com/docs/write-to-farcaster-with-neynar-managed-signers
• Create signer: https://docs.neynar.com/reference/create-signer
• Register signed key: https://docs.neynar.com/reference/register-signed-key
• Signer status: https://docs.neynar.com/reference/lookup-signer
• Publish cast: https://docs.neynar.com/reference/publish-cast
• Farcaster casts guide: https://docs.farcaster.xyz/developers/guides/writing/casts
• Postiz Farcaster setup: https://docs.postiz.com/self-host/providers/farcaster
• Postiz Warpcast settings: https://docs.postiz.com/public-api/providers/warpcast

Google My Business / Google Business Profile (gmb)

gmb publishes a local post to one Google Business Profile location through the legacy Google My Business API v4 accounts.locations.localPosts endpoint, and reads location-level performance metrics through the Business Profile Performance API. Accounts and locations are listed through the v1 My Business Account Management and My Business Business Information APIs.

The provider is is_between_steps = true: OAuth authenticates a Google account, then channelSetupTool selects one business location (an account can own many). Publishing is synchronous — Google either returns the new local post name or rejects it; there is no media-polling phase.

• Rust source: crates/rustiz-providers/src/gmb.rs
• Upstream port: gmb.provider.ts
• Editor: Normal
• Connection mode: oauth + a mandatory location-selection step

Two independent gates. OAuth consent (Testing/Production) is one; the Google Business Profile API access request is the other. Even a perfectly configured OAuth client gets 0 QPM and PERMISSION_DENIED until Google approves the Cloud project for the Business Profile APIs. Approval requires a verified Business Profile active for 60+ days and a website.

Overview

Server Environment Variables

required_env() returns four names because the provider accepts two credential families:

#![allow(unused)]
fn main() {
&[
    "GOOGLE_GMB_CLIENT_ID",
    "GOOGLE_GMB_CLIENT_SECRET",
    "YOUTUBE_CLIENT_ID",
    "YOUTUBE_CLIENT_SECRET",
]
}

required_env_alternatives() collapses each pair:

#![allow(unused)]
fn main() {
&[
    &["GOOGLE_GMB_CLIENT_ID", "YOUTUBE_CLIENT_ID"],
    &["GOOGLE_GMB_CLIENT_SECRET", "YOUTUBE_CLIENT_SECRET"],
]
}

So rustiz providers --status reports gmb as configured when either pair is present. The runtime fallback is per field:

#![allow(unused)]
fn main() {
client_id     = GOOGLE_GMB_CLIENT_ID     or YOUTUBE_CLIENT_ID
client_secret = GOOGLE_GMB_CLIENT_SECRET or YOUTUBE_CLIENT_SECRET
}

Using the YouTube credentials is fully supported: the app and redirect URIs are yours to share. Using separate GMB credentials is cleaner when the GMB app must be verified independently.

rustiz providers --status | jq '.[] | select(.identifier=="gmb")'

Step-by-Step Developer App Setup