Frequently Asked Questions
Product and installation
Do I need both the desktop app and server?
You always need Stib Server. The desktop app is optional: use it for native editor/terminal, preview, windows, downloads, and updater integration. The server also serves the full web client.
Where do agents run?
On the server machine, in the project repository or a card worktree. A desktop client connected to a remote server does not run the agent against an unrelated local checkout.
Which agents are supported?
Stib supports several provider runtimes and exposes the credentials, models, and capabilities actually discovered by your server. Features such as native questions, skills, plan mode, compact, subagents, or goals can vary by provider/version.
Which desktop packages exist?
macOS Apple Silicon: DMG/PKG. Windows x64/x86/ARM64: EXE/MSI. Linux x64/ARM64: DEB/RPM. No AppImage is currently published.
What port does the server use?
A release server prefers 50505, then tries 50506–50514, then an OS-assigned port. Docker always listens on container port 50505. Read port.txt, the tray, startup logs, or the client connection screen for the actual native port.
Where is data stored?
Native data lives in the operating-system application-data directory under stib-server; Docker uses the persistent /data volume. See Server Binary. Project source remains in the configured repositories.
How do updates work?
Desktop and native server packages have separate signed update manifests. Docker is updated by pulling/recreating the image. Back up the server before updating; desktop updates do not migrate or delete server data.
Cards, agents, and Git
Does creating a card immediately run an agent?
It depends on the target column, activation state, and card settings. A passive column does not execute. Active columns may start immediately, while deferred cards wait for activation.
What is the difference between Auto mode and Loop?
Auto mode moves a card through enabled pipeline columns. Loop relaunches it on a schedule while it stays in its current column.
Do sessions survive a page refresh?
The session belongs to the server, not the browser tab. Reopening the card reconnects to its current/persisted state. A server process restart can reconcile or mark abandoned work; it cannot resurrect an external process that no longer exists.
What happens after cancellation or failure?
Messages, session history, and files already written remain. Inspect the Diff and Git workspace before retrying or cleaning the worktree.
Are worktrees automatic?
They are a card option and can be the default, but they require Git and an eligible execution column. A worktree isolates files/index; it does not automatically commit, push, or merge.
Can Stib work without Git?
Limited repository workflows can use a normal directory, but worktrees, branches, diffs/history, and provider review features require Git. Git is strongly recommended.
Accounts and operations
Can several users share a server?
Yes. Server, organization, project, and column roles determine access, subject to licence seats and authentication policy.
Which OIDC providers work?
Stib uses standard OIDC discovery and authorization code with PKCE. A provider works when it supplies compatible discovery, authorization/token endpoints, ID-token claims, and callback registration. Test your exact provider configuration before rollout.
Are API keys the same as agent-provider keys?
No. A Stib API key authorizes project automation endpoints. A provider key lets an agent runtime access a model service. Store and scope them separately.
Is trash a backup?
No. Trash is a retention feature for deleted cards. Use Settings → Server → Backup, store backups independently, and test restoration.
Can I put Stib behind a reverse proxy?
Yes. Forward HTTP and WebSocket upgrades, use HTTPS, and set STIB_SERVER_ORIGIN to the public origin for OIDC. The desktop app connects to that origin without an /api suffix.