goloom

Lightweight, self-hosted social media planning for teams and AI agents.

Plan posts across Mastodon, Bluesky and Friendica from a single Go binary — no enterprise stack, no per-seat pricing.

---

goloom is a self-hosted social media planning application built as one Go binary (API + web UI). It helps teams plan posts across multiple social accounts without the heavy infrastructure and pricing model of typical enterprise-first tools.

Why goloom exists

Most tools in this space are powerful but heavy: complex stacks, many paid tiers, and product scope optimized for large organizations.

goloom was created for one focused outcome:

• plan posts across different social media accounts
• collaborate across teams
• keep operations simple
• integrate cleanly with AI agents such as OpenClaw

Screenshots

Highlights

• Single binary deployment: UI and API in one process.
• SQLite by default: no external database needed.
• PostgreSQL optional for larger deployments.
• Team workspaces with member roles (owner, editor, viewer).
• Scheduling, validation, per-account post versions, media library.
• Built-in analytics for post and account metrics.
• API-first architecture with bearer-token auth.
• OIDC support for browser sign-in.
• Mastodon onboarding can auto-register app credentials from instance URL.

Getting Started

Three ways to run goloom — pick one (full guide: Installation):

• Docker — docker run ... ghcr.io/goloom-app/goloom:latest (see Docker).
• Prebuilt binary — download a static Linux binary from the latest release (goloom_<version>_linux_amd64 / arm64), chmod +x, set ENCRYPTION_KEY + BOOTSTRAP_ADMIN_TOKEN and run it. The web UI is embedded; data goes to ./data/goloom.db (SQLite) by default.
• From source — build it yourself (below).

1) Configure environment

cp .env.example .env

Set required values:

ENCRYPTION_KEY=replace-with-a-long-random-secret
BOOTSTRAP_ADMIN_TOKEN=replace-with-a-strong-bootstrap-token

2) Build and run

make build
./bin/goloom

Open http://localhost:8080.

3) Bootstrap first admin access

Use the bootstrap token in the UI Settings screen. After first login, create normal API tokens and rotate bootstrap secrets.

API Documentation

goloom API is designed for both developers and AI agents. Professional documentation stack uses OpenAPI + Redocly.

Base paths

• Primary: /v1/...
• Alias: /api/v1/... (same handlers, for tools expecting /api/v1)

Authentication

Use bearer tokens:

Authorization: Bearer <oidc-id-token-or-api-token>

API tokens can carry scopes and an optional team binding:

• read permits authenticated GET/HEAD requests. It is independent of write and delete; add it when a client needs to fetch results or use AI-job SSE (/v1/teams/{teamID}/ai-jobs/stream?token=…).
• write includes write:draft and write:schedule; delete includes delete:draft and delete:schedule.
• An unscoped team-bound token retains owner-level management authority inside its bound team when its user is an owner. Team binding limits which team it can access; it does not make the token read-only. User roles still apply.
• Admin routes and user-wide push subscriptions require an unscoped, unbound token. Team-bound tokens cannot read /v1/users, /v1/teams, /v1/me/review-counts or /v1/me/team-notification-prefs, since those responses aggregate data across teams. Use team-specific routes where available.
• Unscoped, unbound tokens and browser sessions retain full access subject to user roles. Restricted tokens cannot be exchanged for browser sessions.

When auto-publish saves an AI result as a draft because the job lacks scheduling permission (including legacy jobs without an authority marker), the completed job exposes result.notice = "saved_as_draft_without_schedule_authority". The same non-error notice appears in the job:result SSE event. Generated result fields are preserved; failed jobs and jobs that create no post receive no notice.

API quickstart (curl)

Health and auth status:

curl -s http://localhost:8080/healthz
curl -s http://localhost:8080/v1/auth/status

List providers:

curl -s http://localhost:8080/v1/providers

Get current identity:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/v1/me

Endpoint groups

• Discovery: /healthz, /v1/providers, /v1/auth/status
• Identity: /v1/me, /v1/me/api-tokens
• Teams: /v1/teams, /v1/teams/{teamID}/members
• Accounts: /v1/teams/{teamID}/accounts, OAuth start endpoints
• Posts: /v1/teams/{teamID}/posts, validation, versions, cancel
• Analytics: /v1/teams/{teamID}/analytics*, post analytics
• Admin: /v1/admin/*, provider instance management

For complete route list, see api/http.go.

API docs

The interactive API reference is rendered with Scalar and served by the website at /api/. It reads the OpenAPI spec directly, so there is no separate static build step.

Lint the OpenAPI spec:

make docs-api-lint

• source spec: docs/api/openapi.yaml (single source of truth)
• the spec is copied to website/public/openapi.yaml by make website-build

AI agent integration notes (OpenClaw and similar)

• Built-in MCP server (Streamable HTTP transport) at /mcp (enabled by default, MCP_ENABLED), authenticated with API tokens carrying read / write:draft / write:schedule / write / delete scopes (unscoped tokens have full access).
• Stable JSON responses across core endpoints.
• Predictable resource paths with team-scoped objects.
• Validation endpoint before scheduling: POST /v1/teams/{teamID}/posts/validate.
• API token lifecycle endpoints for secure agent onboarding.

Website & Documentation

The project website (Astro + Starlight) lives in website/: a marketing landing page, the documentation (3-column Starlight layout) and the Scalar API reference at /api/.

Local dev server:

make website-dev

Build static site (includes API docs):

make website-build

Generated output: website/dist/

Deployed via GitHub Pages on push to main when website/ or docs/api/ changes: the pages.yml workflow builds the site with make website-build and force-pushes website/dist to the org Pages repo goloom-app.github.io, which GitHub serves at the root URL https://goloom-app.github.io/.

Provider Support

Mastodon

• OAuth account connection
• optional automatic app registration via instance URL
• publishing and metrics (likes, reposts, replies)

Friendica

• manual provider app credentials
• publishing and Mastodon-compatible metrics

Bluesky

• account connection with app password
• publishing and metrics support

Deployment Options

Default (single binary + SQLite)

Best for low-ops environments and small-to-medium teams.

DATABASE_URL=file:./data/goloom.db

PostgreSQL

Use when you need external DB operations and scale patterns:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/goloom?sslmode=disable

Upgrading PostgreSQL to a new major version (e.g. 16 → 18) is a dump & restore, not an in-place swap — see the PostgreSQL major upgrade guide.

Kubernetes (Helm)

A Helm chart is provided at deploy/helm/goloom (SQLite on a PersistentVolume, or external PostgreSQL; optional Ingress):

helm install goloom ./deploy/helm/goloom \
  --namespace goloom --create-namespace \
  --set secret.encryptionKey="$(openssl rand -hex 32)" \
  --set secret.bootstrapAdminToken="change-me-please" \
  --set config.publicBaseUrl="https://goloom.example.com"

See the Kubernetes (Helm) guide.

Production migration (Docker → Kubernetes)

If you run Goloom with Docker PostgreSQL and want to move to the homelab CNPG deployment, see docs/migrations/docker-to-kubernetes-homelab.md.

Docker

Use the published multi-arch image (linux/amd64 + arm64) from GHCR:

docker run --rm \
  -p 8080:8080 \
  -e ENCRYPTION_KEY=replace-with-a-long-random-secret \
  -e BOOTSTRAP_ADMIN_TOKEN=replace-with-a-strong-bootstrap-token \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/goloom-app/goloom:latest

For production, pin a version tag (e.g. ghcr.io/goloom-app/goloom:v0.1.0) instead of :latest. To build the image yourself: docker build -t goloom ..

Development

nix develop
make run

Frontend-only dev server:

make frontend-dev

Recommended API-doc workflow in CI:

• run make docs-api-lint on pull requests to validate the OpenAPI spec
• the reference is published as part of the website (make website-build)

Configuration

Start from .env.example. Common keys:

• APP_ENV, HTTP_ADDR, PUBLIC_BASE_URL
• DATABASE_URL
• ENCRYPTION_KEY
• BOOTSTRAP_ADMIN_*
• SCHEDULER_*
• OIDC_*
• MASTODON_*

Positioning vs heavy platforms

goloom is intentionally optimized for:

• lower runtime overhead
• easier self-hosting
• practical team collaboration
• API-first automation for agent workflows

If you need broad enterprise suites, many commercial upsell modules, or advanced campaign ecosystems, other products may fit better. If you need a focused scheduler with strong API ergonomics and simple ops, goloom is the target shape.

Security notes

• Provider access tokens are encrypted at rest.
• API tokens are stored as hashes.
• Set strong ENCRYPTION_KEY and rotate bootstrap/admin secrets after setup.

Versioning & releases

goloom follows Semantic Versioning and is intentionally pre-1.0 (0.x) — usable and self-hostable today, but breaking changes can still land between minor versions, so pin a version and read the notes before upgrading.

• Branching: development happens on feature branches; after testing they are merged into main (CI runs the full test suite on every PR).
• Nightly: every push to main publishes ghcr.io/goloom-app/goloom:nightly, always built from the latest main state (plus a per-commit nightly-<sha> tag). Use it to try upcoming features; it is not a release.
• Releases are automated from Conventional Commits via release-please: a release PR maintains CHANGELOG.md and the version; merging it tags vX.Y.Z, publishes a GitHub Release with prebuilt Linux binaries (amd64/arm64), and pushes the versioned ghcr.io/goloom-app/goloom image — :latest moves only on releases.
• The running version is reported by GET /healthz and the agent discovery doc.
• The REST API has its own contract version under /v1, independent of the app version; it changes only on breaking API changes.

About this project

goloom grew out of my own needs as a self-hosted tool. It is built with heavy use of AI, and I use it as a testbed for exploring methods for efficient, AI-assisted development.

License

Licensed under the MIT License.