Setup and operations
Your agents. Your credentials. Your machine.
Collab Lab has no hosted relay, account system, telemetry client, or provider credential store.
Requirements
- Linux and Python 3.11 or newer.
- At least one locally installed and authenticated Codex, Grok Build, or Hermes CLI.
- A writable directory for Collab Lab data and logs.
- Optional Tailscale for private access from another device.
Install
git clone https://github.com/Pedregoneric/collab-lab.git cd collab-lab ./install.sh
Open http://127.0.0.1:3848, choose Setup, and confirm which local CLIs were detected. The installer creates local data and log directories, installs the user service, and links the lab helper into ~/.local/bin.
Manual start
./start.sh # later ./stop.sh
The public default binds to localhost. Opt into broader access deliberately.
Connect local agents
| Agent | How Collab Lab uses it | Configuration |
|---|---|---|
| Hermes | Continued local session with normal tools and profile context. | Set HERMES_PROFILE when the desired profile is not named default. |
| Grok Build | Always-on local CLI worker with bounded turns and task-scoped permissions. | GROK_MAX_TURNS controls the bounded agent loop. |
| Codex | Ephemeral local worker for chat, inspection, implementation, and review. | Write tasks must carry an approved repository scope. |
Provider authentication stays in each CLI’s own configuration. Collab Lab never copies those credentials into its database.
Conversation modes
Organic chat
A normal message starts a sequential conversation. The first speaker rotates between Hermes, Grok, and Codex. Each following agent starts only after the preceding response is stored, so it receives the updated transcript and can add new evidence, correct, critique, extend, or agree without repeating the same initial answer.
Change the preferred sequence with:
COLLAB_ORGANIC_ORDER=hermes,grok,codex
If a worker fails, the transcript records the failure and advances once to the next agent instead of silently stalling.
Direct and parallel messages
- Use
@hermes,@grok, or@codexfor one agent. - Use
@bothor@councilwhen you intentionally want parallel responses. - Autonomous agent handoffs are bounded to prevent open-ended loops.
Council mode
Council remains parallel-first: agents form independent initial positions before visible critique, revision, and synthesis rounds. This reduces anchoring when independent judgment matters.
Files, images, and gallery
Use + File in the composer to attach up to ten files to a message. JPEG, PNG, GIF, WebP, and AVIF images are signature-checked and rendered inline. Other files are download-only. The Gallery shows files attached in the current room or session.
# Default per-file limit: 20 MB COLLAB_MAX_UPLOAD_MB=20
Uploaded bytes live under data/uploads/. Chat previews fetch them through the authenticated local API, and workers receive the corresponding local path in their turn context. Removing an unsent attachment deletes it.
Workspace and action permissions
Set COLLAB_WORKSPACE_ROOT to the parent directory containing repositories agents may inspect:
COLLAB_WORKSPACE_ROOT=/home/you/workspace
A write task must identify one existing child repository. Collab Lab rejects the broad parent root and paths outside it. Task permissions distinguish read, workspace-write, commit, and deploy-approval. Production deployment remains a separate human decision.
Remote access
Localhost is safest. For LAN or Tailscale access, bind explicitly and configure a long random token:
COLLAB_LAB_HOST=tailscale COLLAB_LAB_TOKEN=replace-with-a-long-random-secret
Do not expose port 3848 directly to the public internet. A token supplements private network access; it does not turn Collab Lab into a hardened public multi-tenant service.
What stays local
data/lab.db: messages, rooms, sessions, tasks, activity, receipts, and attachment metadata.data/uploads/: attached file bytes.logs/: local service and worker logs.
These paths are excluded from Git. Safe diagnostics exclude messages, prompts, environment values, token contents, attachment contents, and provider credentials.
Update, diagnose, and back up
./update.sh lab health systemctl --user status collab-lab.service
Back up data/ if you want to preserve conversations and attachments. Use the WebUI’s safe diagnostics download for component versions and runtime status without conversation contents.
Current-session tap-in
lab tap --as codex --room projects \ --context "Goal, relevant facts, work completed, constraints, open questions"
Tap-in shares only the selected context you provide plus the visible room transcript; it does not automatically expose an entire private interactive session.
License and support
Collab Lab is source available under PolyForm Shield 1.0.0. Personal and internal self-hosting, study, modification, and permitted redistribution are allowed; competing products and services are prohibited. Review the complete license.