logo
Hermes AgentHermes Agent + Postiz

How to Install the Postiz Skill in Hermes Agent

  • Install Hermes Agent, then the Postiz CLI
  • Add the skill: npx skills add gitroomhq/postiz-agent
  • Authenticate with a Postiz API key or OAuth login
Start for $0
What Hermes Agent Can Do

Postiz is the agentic social media scheduling platform that Hermes Agent drives through the Postiz skill and CLI. Please make sure there is always a human in the loop. Last updated: September 2026.

What do I need before installing?

You need three things: a machine or server for Hermes Agent (Linux, macOS, WSL2, or Windows), Node.js with npm for the Postiz CLI, and a Postiz account with at least one social channel connected. If you only want the commands, they are here; each step is explained below.

1Install
a few minutes

Run this in your terminal

Four commands install Hermes Agent, the Postiz CLI and the skill, then sign you in. Everything runs on your own machine or server.

terminal
# 1. Install Hermes Agent and run setup
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup

# 2. Install the Postiz CLI
npm install -g postiz

# 3. Add the Postiz skill
npx skills add gitroomhq/postiz-agent

# 4. Authenticate (API key or OAuth device flow)
export POSTIZ_API_KEY=your_api_key   # or: postiz auth:login
postiz auth:status
hermes skills list                   # postiz should be listed

Prefer no CLI? Add the Postiz MCP server to ~/.hermes/config.yaml instead; the config is further down this page.

2Ask
live in Postiz

Ask Hermes to post for you

Once the skill is loaded, Hermes runs the postiz CLI for you. Posts publish at the scheduled time even after the session ends.

Draft a LinkedIn post about our launch as a Postiz draft for tomorrow at 9am.

Hermes Agent

Ran postiz posts:create -s 2026-09-25T09:00:00Z --draft on your LinkedIn channel. Draft created. Review it in Postiz and I can move it to the queue.

via PostizLinkedin

Also try

List my connected Postiz channelsPost this to X tomorrow at 9amShow the required settings for my Reddit channel
  1. 1Install Hermes Agent with the install script, then run hermes setup
  2. 2Install the Postiz CLI globally with npm install -g postiz
  3. 3Add the skill with npx skills add gitroomhq/postiz-agent
  4. 4Export POSTIZ_API_KEY or run postiz auth:login, then postiz auth:status
  5. 5Run hermes skills list and ask Hermes to list your Postiz channels

One skill install powers every channel you run

Connect your accounts in Postiz once. From then on Hermes Agent can post to any of them from your terminal, Telegram or Discord, and Postiz publishes at the time you set.

Hermes Agent
XLinkedInInstagramFacebookThreadsRedditYouTubeTikTokPinterestBlueskyDiscordSlackGoogle BusinessTelegramMastodonDribbbleWordPressMediumHashnodeDev.toTwitchKickWarpcastNostrLemmyVKMeWeWhopSkoolListmonk

How do I install the Postiz skill in Hermes Agent, step by step?

Follow the five steps in order. Each one is a single command, and the whole setup usually takes a few minutes.

  1. 1

    Install Hermes Agent and run setup

    Hermes Agent is an open-source (MIT) AI agent by Nous Research that runs on your own machine or server. The install script works on Linux, macOS, WSL2, and Termux; Windows uses a PowerShell installer. hermes setup then walks you through the model provider (Nous Portal, OpenRouter, OpenAI, or your own endpoint) and can migrate an existing OpenClaw install.
    Step 1
    # Linux, macOS, WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# Full setup wizard
hermes setup
  2. 2

    Install the Postiz CLI

    The Postiz skill is a set of instructions for the postiz command-line tool, so the binary has to exist on the same machine Hermes runs on. Install it globally with npm or pnpm. Every command it exposes returns JSON, which is what makes it easy for an agent to chain calls.
    Step 2
    npm install -g postiz
# or
pnpm install -g postiz

postiz --help
  3. 3

    Add the Postiz skill

    The skill is published as a SKILL.md in the agentskills.io format that Hermes Agent reads. Install it with the skills CLI. Hermes loads skills from ~/.hermes/skills, so if the skill does not show up in hermes skills list, copy the postiz folder there. The skill source is on GitHub.

    Step 3
    npx skills add gitroomhq/postiz-agent

# Confirm Hermes sees it
hermes skills list

# Skills live here
ls ~/.hermes/skills
  4. 4

    Authenticate with Postiz

    Create an API key under Settings in your Postiz dashboard and export it as POSTIZ_API_KEY where the Hermes process can read it, or run postiz auth:login for an OAuth device flow that stores credentials locally with no key to copy. Your social account logins stay inside Postiz; Hermes only ever holds this Postiz credential.
    Step 4
    # Option A: API key
export POSTIZ_API_KEY=your_api_key

# Option B: OAuth device flow
postiz auth:login

# Self-hosted Postiz? Also set:
export POSTIZ_API_URL=https://your-postiz.example.com/api

postiz auth:status
  5. 5

    Verify with a first request

    Ask Hermes to list your connected channels. If it returns your accounts, the skill, the CLI, and the credentials are all working. Then try scheduling a draft so you can review it in Postiz before anything goes live. To talk to Hermes from Telegram, Discord, Slack, WhatsApp, or Signal, run hermes gateway setup and hermes gateway start.
    Step 5
    > List my connected Postiz channels

Hermes Agent: You have 3 channels connected:
  X, LinkedIn, and Reddit.

> Draft a LinkedIn post about our launch as a
  Postiz draft for tomorrow at 9am

Hermes Agent: Draft created. Review it in
  Postiz and I can move it to the queue.

Can I connect Hermes Agent to Postiz over MCP instead?

Yes. Hermes Agent supports remote MCP servers, so you can skip the CLI and add the Postiz MCP server to ~/.hermes/config.yaml. Hermes opens a browser for the OAuth login once and exposes the tools as mcp_postiz_<tool>. No API key is stored, and the server includes the full Postiz toolset.

~/.hermes/config.yaml
mcp_servers:
  postiz:
    url: "https://mcp.postiz.com/mcp-oauth-dynamic"
    auth: oauth

The Hermes Agent overview has a side-by-side comparison of the skill and the MCP server.

Why is the Postiz skill not working in Hermes Agent?

Almost every failure comes down to one of seven causes. Postiz returns a JSON error that Hermes can read, so asking it "what went wrong?" usually points at the row below.

SymptomFix
hermes skills list does not show postizHermes loads skills from ~/.hermes/skills. Check that a postiz folder with SKILL.md exists there; if the installer put it elsewhere, copy the folder into ~/.hermes/skills and restart Hermes.
Commands fail with an authentication errorRun postiz auth:status in the same environment Hermes uses. Either export POSTIZ_API_KEY (from Postiz settings) where the Hermes process can read it, or run postiz auth:login to complete the OAuth device flow.
Hermes says no integrations were foundConnect your social accounts in the Postiz dashboard first. Hermes only sees channels that already exist in Postiz; run postiz integrations:list to confirm they appear.
The post is rejected because of the mediaEvery file must go through postiz upload first, and the returned path is what posts:create accepts. Raw file paths and external URLs are rejected, especially by TikTok, Instagram, and YouTube.
The post is scheduled at the wrong timePostiz schedules use ISO 8601 timestamps in UTC. Tell Hermes your timezone, or say the time as UTC, so it converts correctly when it calls posts:create -s.
A platform rejects the post over a missing settingAsk Hermes to run postiz integrations:settings <id> for that channel. It returns the required fields, such as a Reddit flair or a YouTube title, so Hermes can fill them in and retry.
You self-host Postiz and the CLI talks to the cloudSet POSTIZ_API_URL to your own Postiz server's API URL alongside POSTIZ_API_KEY. The CLI and the skill respect it, so Hermes posts through your instance.

Installing Postiz in Hermes Agent: frequently asked questions

Does npx skills add work with Hermes Agent?

Yes. Hermes Agent follows the agentskills.io SKILL.md standard, and npx skills add gitroomhq/postiz-agent installs the Postiz skill in that format. After installing, run hermes skills list to confirm Hermes sees it. If it is missing, copy the skill folder into ~/.hermes/skills, which is where Hermes loads skills from.

Where does Hermes Agent store skills?

All skills live in ~/.hermes/skills, which Hermes treats as the single source of truth. Each skill is a folder containing a SKILL.md file. You can browse and install community skills with hermes skills browse and hermes skills install, and every installed skill is also available in chat as a slash command.

Do I need a Postiz API key if I use OAuth?

No. The Postiz CLI supports two authentication methods: an API key set as POSTIZ_API_KEY, or postiz auth:login, which runs an OAuth device flow and stores credentials locally. Either works for Hermes Agent. If you connect through the Postiz MCP server instead, Hermes handles OAuth itself with auth: oauth in config.yaml.

Can I use the Postiz MCP server with Hermes Agent instead of the skill?

Yes. Hermes Agent supports remote MCP servers. Add a postiz entry under mcp_servers in ~/.hermes/config.yaml with url set to https://mcp.postiz.com/mcp-oauth-dynamic and auth: oauth. Hermes exposes the tools as mcp_postiz_<tool>, opens a browser once for login, and no API key is needed. The MCP server includes the full Postiz toolset.

Can Hermes Agent use a self-hosted Postiz instance?

Yes. Set POSTIZ_API_URL to your server's API URL in the same environment as POSTIZ_API_KEY. The Postiz CLI reads both, so every command Hermes runs goes to your instance instead of the hosted service.

How do I update or remove the Postiz skill in Hermes Agent?

To update, re-run npx skills add gitroomhq/postiz-agent to refresh the SKILL.md and npm update -g postiz to update the CLI. To remove it, delete the postiz folder from ~/.hermes/skills and uninstall the CLI with npm uninstall -g postiz. Revoking the API key in Postiz cuts off access immediately.

How do I talk to Hermes Agent from Telegram or Discord after installing?

Run hermes gateway setup to connect the chat platforms you want, then hermes gateway start to run the gateway. Hermes supports Telegram, Discord, Slack, WhatsApp, Signal, email, and more. Once connected, a message like "post this to X tomorrow at 9am" from any of them triggers the Postiz skill.

What should I read next?

Once the skill is installed, the Hermes Agent overview shows everything you can ask for, and each platform guide lists the exact settings Hermes can apply, for example X, LinkedIn, Instagram, Reddit, and YouTube.

Hermes Agent overview

Postiz for any AI agent

Postiz MCP server

Postiz pricing

Postiz CLI docs

Hermes Agent docs

Ready to install?

Create your Postiz account, connect your channels, and Hermes Agent can start posting in minutes.