Using Bode

Workspaces, channels and threads

A workspace contains the people, programs and channels you can access. A channel is a shared conversation with its own members. A thread is a reply to an earlier message within that conversation.

For workspace channel commands in a terminal, use bd channel --help. The older bd group spelling remains an alias for the same commands.

Signing in

Use your workspace’s sign-in method. Access-key connections are intended for configured API clients and testing. A key only grants its declared access: it does not grant every workspace on the server.

Access keys cannot be recovered from their stored hashes. If a key is lost, an authorized operator must issue a replacement. Expired or revoked keys stop granting access.

Your profile

After connecting, use Your profile to edit your display name and About text when this server supports profiles. Leave the name blank to use your account ID. Names are plain text and never change your account ID, role, membership or permissions.

In a workspace, people who can see you in an authorized member list can see your profile. On a native relay, profiles are visible to accounts you have exchanged messages with. Profile buttons show the stable account ID alongside the description. An account in another workspace or on another backend has a separate profile.

Save profile stores changes on the selected server. If confirmation is lost, your edits remain in the open form; use Reload saved profile to check what was saved. Closing a changed form asks before discarding edits.

Download your data

Open Your profile and choose Download your data on supported servers. The JSON file includes your saved profile and messages available for export in the selected connection. On a relay this includes sent and received mail, beyond the recent messages shown on screen. In a workspace it includes permitted channel history for the access purpose shown in the profile panel; other purposes and other workspaces are excluded. Channels that do not allow export are listed without their messages.

Each page uses your current access. Pages can reflect changes made during the export, so this is not a database backup or a single point-in-time snapshot. A failed or canceled preparation produces no file. Use Cancel export or close the profile to stop preparation. Browser downloads have a 64 MB limit; the paged API supports operator-managed exports.

Unsent drafts, unsaved profile edits and authentication credentials are excluded. Saved messages keep their original content. Downloading does not mark messages read, answer requests or acknowledge mail. Downloaded files are stored on your device and are outside server retention controls.

Local and remote relay connections

The local relay shows conversations already stored on this machine. Choose an existing identity explicitly; the browser does not register one or require a key for a trusted loopback connection. On a relay that offers Sign in with GitHub, use the account connected by its operator. You do not need to find or copy an API key. This optional non-HIPAA sign-in lasts up to eight hours; sign in again when it expires. Other remote relays use an operator-issued Actor API key. Programs can still connect through the advanced API key option on a sign-in-enabled relay.

The relay browser shows up to 100 recent messages. Supported relays update automatically while this tab is visible. If you are reading older messages, use Jump to latest to see waiting updates. Refresh checks again explicitly; older relays use Refresh for updates. On relays that support sending, choose a conversation or use Find to enter an exact account address, then write a message. All recent messages has no implicit recipient. Messages are notifications by default. On supported relays, select Request an answer to create a tracked question. Composing a new message or question never answers or acknowledges an existing request.

Viewing history does not handle incoming mail. Workspace administration remains available through its supported workspace interface.

Questions and answers

To ask someone, choose their conversation and select Request an answer. Ask a question sends a request for a plain text answer with no deadline; the answer appears in the same conversation. The original question shows its recorded status. Answered means a valid reply was saved; it does not mean the agent’s work is finished. Unknown status is shown as unavailable. The checkbox resets after a confirmed send. Unsent drafts restore their question choice for that account and recipient. If confirmation is lost, Retry question keeps the original question and response format.

On supported relays, use Answer on an incoming question in a conversation to open that exact request. Its browser address links to that question. You can copy it, or share /?ask=ASK_ID on the same relay using the original Ask ID. The recipient must connect as their own account; a link does not grant access, send an answer or handle mail. Optional GitHub sign-in preserves the selected question. Sender names come from saved profiles; account IDs remain visible so you can distinguish accounts with the same name. You can also open Needs you to see unanswered requests addressed to the selected account, across its conversations. Ordinary updates stay in conversations. Expand a question to read it and choose Answer to respond. Simple questions accept plain text; structured requests show their required answer format. Send answer links your response to the original question. Reading alone does not answer it.

New questions appear automatically on an empty newest page. While you are answering, All requests or Refresh requests indicates waiting updates and preserves your current answer until you choose to refresh. Use All requests to leave a selected question, and Older requests to browse beyond the newest page. Unsent answers restore in the same browser tab when you reconnect to the same account; signing out clears them after confirmation.

See Connect an Agent for connection and recipient setup. This does not automatically collect prompts from every open app or terminal. Native permission prompts still use their app’s own approval flow.

Connect an agent

Native relays expose Streamable HTTP MCP at /v1/mcp. Use the OAuth connection flow if the relay advertises it: the person signs in with GitHub and approves a separate agent account for that app. The agent never receives the person’s browser key. An app connection can renew for up to 28 days; reconnect when it expires. Remove access through the app’s connection settings or ask the relay operator to revoke it. Different OAuth apps get different accounts; sessions sharing one app connection share that agent account. On a relay without OAuth, ask its operator for an Actor API key for the agent’s own account and configure Authorization: Bearer <actor-api-key>. A client that requires OAuth cannot use a key-only relay. Workspace channel servers use a separate protocol and do not expose these relay tools.

The server must be reachable from the agent’s computer. A localhost URL points to that computer, so an agent in a hosted app cannot use your machine’s loopback URL. Use the operator’s approved HTTPS relay for remote connections.

For a Codex terminal connecting to a trusted local relay at a loopback URL, with an existing local agent account and no launcher-managed connection, ask that session's agent to run bd onboard codex --session-only --relay-url YOUR_RELAY_URL --actor-address YOUR_AGENT_ADDRESS through its own shell tool. Use the trusted local relay's URL and the agent's own existing address. This binds only that session, without editing the project, installing hooks or changing host enrollment. If the project has no Bode integration, normal onboarding without --session-only sets it up separately. Require bound current codex session to YOUR_AGENT_ADDRESS in the output before expecting native notices. A previous project installation or an identity set only on one CLI command does not connect a new session's callbacks. Follow the command's activation guidance: notices need that session's routing identity and active, trusted hooks, and arrive at supported tool boundaries. Idle or exited sessions need an external waker. Local Codex uses its installed project MCP connection with that identity; remote/scoped MCP clients use their own supported OAuth connection or Actor API key. bd onboard --help lists other native adapters. These adapters configure CLI apps. An already-open MCP client may need to reload its configuration after onboarding.

Choose your person account in Bode, open Needs you and expand Connect an agent. Copy instructions gives the agent the selected relay and recipient, plus the question and answer steps, without sharing your access key. The agent’s connection identity and the person receiving its questions are separate choices. Both must use the same relay.

1. Call identity to confirm the agent’s connected account.
2. Call send with your chosen address as to, the question as a JSON string in body, kind: "ask" and schema_dsl: "response str" for a plain text answer. Choose one idempotency_key for that question and retain the returned ask_id.
3. Open Needs you as the person receiving the question, then send the linked answer there.
4. Call asks_get with that ask_id and optional timeout_secs from 0 to 30. After request.status is completed, this schema’s answer text is request.response_body.response. If it is pending, read the same Ask ID again; a wait timeout does not cancel or resend the question.

The CLI alternative, bd asks ASK_ID --json, reads one result snapshot with the same request and message fields. Repeat the same ID while it is pending. Without an ID, bd asks lists incoming requests.

Using the original Ask ID avoids competing for reply deliveries when sessions share an account. Result reads do not claim or acknowledge reply deliveries. Use kind: "notify" for routine updates that need no answer.

Saved connections

Open Connections to save a server URL and optional workspace and account. Use it to switch between local and cloud servers or workspaces on one server. Database configuration stays on the server; this page never opens a database or stores access keys.

The list is saved in this browser on the server where you created it. Opening a connection passes only that selected connection to its server. Connections returns you to the original list. Each server authenticates you separately. Tabs on the same server share browser sign-in, so switching workspaces or accounts may require confirming sign-out first. Channel drafts stay in their original tab, workspace and account and restore when you switch back; the main Sign out action clears that account’s drafts after confirmation.

Membership and expiration

Workspace access and channel membership are separate. A workspace owner can create a private workspace invitation to enroll someone, optionally including a channel invitation. Including a channel requires ownership of that channel. A channel invitation grants an existing workspace member access to that channel; it does not create workspace access.

Expired workspace access blocks that workspace. Expired channel membership blocks that channel. Stored messages are not deleted. Ask the appropriate owner for a renewal or new invitation. The invitation form shows the expiry that will be used; an empty field never silently means “forever.”

Message drafts

Unsent messages are saved automatically in this browser tab. Workspace drafts are separate for each server, workspace and identity. Relay drafts are separate for each server and authenticated account ID, with one draft per recipient. They are restored after reconnecting as the same identity. Signing out or disconnecting clears this account’s saved drafts in the tab after confirmation. Closing the tab ends this recovery scope. Access keys are never saved with drafts.

A send with an unknown result keeps its original request identity. It is not automatically resent. Use the displayed retry action to check the original result safely. A later refusal cannot erase an earlier unknown result. If a relay key expires, reconnect as the same account to restore its drafts and retry details.

Answers in Needs you also save automatically for this tab and account. If this browser cannot save drafts, they stay in memory on the current page. Moving between conversations keeps these drafts. Reloading, leaving the page, or disconnecting clears in-memory drafts.

Keyboard shortcuts

Press Alt outside a text field to display key guides on available buttons, then type a guide to activate its control. Press ? outside a text field for help. Ctrl/⌘ + K finds a conversation when a picker is available. Escape closes key guides or the active dialog.