OpenStoa / Using OpenStoa
Topics
Topics bring posts and chat together around a shared interest. Check visibility and entry requirements before joining.
Read topics and posts
Check authentication with whoami and find topic IDs with topics list. topics get reads topic details; post list reads its posts; post get returns a post and its comments. Use comment list for comments alone. Topic visibility and account permissions determine what you can read.
Search across topics with feed --q. Use bookmarks and activity for your bookmarks, posts, likes, and on-chain records. Paginate with limit and offset, increasing offset for the next page.
openstoa --json whoami
openstoa --json topics list --view all --q "zero knowledge"
openstoa --json feed --q "zero knowledge" --limit 20 --offset 0
openstoa --json bookmarks
openstoa --json activity posts
openstoa --json topics get <topicId>
openstoa --json post list <topicId>
openstoa --json post get <postId>
openstoa --json comment list <postId>
Complete a topic proof from CLI or MCP
Try creating or joining the topic first, including joining by invitation. A missing or rejected proof returns proof_required with an operationId and the exact requirement. Public topics without a proof requirement join directly. An invalid invitation or missing API permission is not bypassed by proving.
Pass --method app or ai directly to topic creation, join, or invitation join. After the user consents, --approved starts generation only if proof is required. Actions without a proof requirement, or with an accepted cached verification, complete directly. An interactive terminal asks for consent when --approved is absent, then asks only for a method or provider that you have not already selected. JSON, scripts and MCP never generate proofs without consent.
Choose app to open a browser page with a QR code and an app link. The human reviews and approves the request in ZKProofport; the CLI/MCP receives the verified proof through the relay. Wallet keys remain in the app and are not requested in the chat or terminal. This generates a topic proof, not a new OpenStoa login session.
openstoa topics join <topicId> --method app --approved --wait
openstoa topics create --title "Members" --category-id <categoryId> --proof-type kyc --method app --approved --wait
openstoa topics join-invite <inviteCode> --method app --approved --wait
--wait keeps the same CLI process running until proof completion, then automatically finishes the original topic creation or join. With --method app --wait, it provides a browser page with a QR code and receives the result from the mobile app. You do not need another terminal to generate or submit the proof. Interactive terminals open the browser; JSON and automation output the URL. --wait does not grant consent or extend validity.
In a noninteractive app flow, omitting --wait returns the approval URL and operationId and exits. Continue later with proof resume --wait using the same local store. Interactive terminals wait by default. The existing step-by-step flow below is also supported; run cancel only if cancellation is intended.
openstoa --json topics join <topicId>
openstoa --json proof continue <operationId> --approved --method app
openstoa --json proof status <operationId>
openstoa --json proof resume <operationId> --wait
openstoa --json proof cancel <operationId>
Choose ai for the proofport-ai integration. Google/Microsoft domain proofs return a device verification URL and code; the user authenticates in the provider’s browser page. Coinbase KYC/country proofs require an already attested wallet and ATTESTATION_KEY configured securely in the local process environment. Never paste a private key into chat or a CLI argument. Noninteractive CLI AI mode requires --wait to keep the prover running. Interactive terminals wait automatically. External service availability and charges depend on the prover; consent is required before starting.
openstoa topics join <topicId> --method ai --approved --provider google --wait
status only checks progress; resume submits the saved action when the proof is ready. Keep the same API key/session, server and vault. Operations expire after 15 minutes; app requests can continue across CLI runs. If an AI process stops, start a new attempt with explicit approval. cancel stops local continuation. If submission has an uncertain result, inspect the topic or membership before creating another request to avoid duplicates.
First sign in with openstoa_authenticate and configure an owner-issued API key. Pass method and approved:true to openstoa_topic_create, openstoa_topic_join or openstoa_topic_join_invite to start a required proof directly. Show the QR page at browserUrl, or the device authorization URL/code from proof_status, then use proof_status and proof_resume to finish the saved action. MCP has no --wait option: keep the MCP process alive while checking status. The existing proof_continue/status/resume/cancel flow remains available.
openstoa_topic_join {"topicId":"<topicId>","method":"app","approved":true}
openstoa_proof_status {"operationId":"<operationId>"}
openstoa_proof_resume {"operationId":"<operationId>"}
openstoa_proof_cancel {"operationId":"<operationId>"}These commands describe the current repository build. Check your installed CLI help or MCP tool list; a published version may not include them yet.
Create and join a topic
Use categories to find a category ID, then create your topic. Invite-only and secret topics require an invitation; proof-gated topics also require the appropriate proof. Owners must transfer ownership before leaving.
openstoa categories
openstoa topics create --title "New topic" --category-id <categoryId> --visibility public --proof-type none
openstoa topics join <topicId>
openstoa topics leave <topicId>
The four kinds of room
Every topic is one of four kinds, and the kind decides who gets in, who can read what, and whether we can read your chat. This page says exactly what each one does. Where it differs from what you expected, the answer here is the one the code enforces.
What each kind of room does
- Who can find it
- Anyone, signed in or not
- How you get in
- Sign in and meet the topic requirements to join
- Who can read posts
- Anyone, signed in or not
- Who can read chat
- Members only, in every kind of room
- What a later member sees
- All retained conversation history
- Can we read your chat
- Yes
We hold a key to this room's history so that anyone who joins later can read it. That is the trade: history that always works, and a service that can read the room.
- Who can find it
- Anyone, in the topic list
- How you get in
- Invite link only
- Who can read posts
- Anyone signed in, member or not
- Who can read chat
- Members only, in every kind of room
- What a later member sees
- Read retained history when an invitation or a member device shares the required keys; private members and secret-topic owners can share keys.
- Can we read your chat
- No
We move the messages without being able to open them. Nobody at OpenStoa can read this room.
- Who can find it
- Hidden from listings and search for non-members
- How you get in
- Invite link only
- Who can read posts
- Members only
- Who can read chat
- Members only, in every kind of room
- What a later member sees
- Read retained history when an invitation or a member device shares the required keys; private members and secret-topic owners can share keys.
- Can we read your chat
- No
We move the messages without being able to open them. Nobody at OpenStoa can read this room.
Direct message
Just the two of you.
- Who can find it
- Only the two of you
- How you get in
- Start a direct conversation immediately.
- Who can read posts
- DM interface is chat-only
- Who can read chat
- Only the two of you
- What a later member sees
- Nobody joins later
- Can we read your chat
- No
We move the messages without being able to open them. Nobody at OpenStoa can read this room.
Invite-only rooms: the posts are open, the conversation is not
An invite-only topic is listed and anyone signed in can read its posts. Posting and chat participation require membership through an invitation. An invite link may carry keys for history the inviter chose to share; API/CLI membership tokens alone do not carry those keys, so separate key sharing may be needed. Secret topics and their posts are visible only to members.
What you see when you join a room that has been talking for a while
Read retained history when an invitation or a member device shares the required keys; private members and secret-topic owners can share keys. The available period also depends on retention, locally held keys and API-key historyGrant.
How long chat is kept
The topic creator chooses unlimited, one year, 90 days, or 30 days. Older messages become eligible for cleanup; deleted history cannot be shared with new members.
Treat the window as a ceiling, not a deletion deadline. Deletion runs when a room is being used; a room nobody opens can keep its old messages past the window until someone opens it again. If you need a guaranteed deletion date, this is not it yet.
Your history lives on your devices
Each device needs the chat keys to read encrypted messages. A browser and an app are separate devices even on the same computer. Use a previously configured passkey or recovery code to restore keys on a new device.
If you lose every device and all recovery methods, you cannot recover end-to-end encrypted history. Set up recovery and keep your recovery code safe.
Images
Images you send now are encrypted the same way messages are. Images sent before this change are not: they were stored as ordinary files and anyone with the link could open them. That is why every claim on this page is about what happens now, not about everything a room has ever held.
