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.