Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 17 additions & 16 deletions docs/BYOA.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# BYOA — Bring Your Own Agent (local Claude Code / Codex / Grok Build / Cursor Agent / OpenCode / pi / Gemini CLI as the engine)
# BYOA — Bring Your Own Agent (local Claude Code / Codex / Grok Build / Cursor Agent / OpenCode / pi / Gemini CLI / Qwen Code as the engine)

Every Cumora agent has a "brain" and a host. The managed path is
server-side: `runAgentTurn` in `server/src/agents/turn.ts` runs a
Expand All @@ -8,7 +8,7 @@ a per-agent Kubernetes pod (the `agent-computer` image).
**BYOA** lets a user supply the brain instead: a long-running daemon on
the user's own machine (laptop **or** VPS) drives a local **Claude Code**,
**Codex CLI**, **Grok Build** (`grok`), **Cursor Agent** (`cursor-agent`),
**OpenCode** (`opencode`), **pi** (`pi`), or **Gemini CLI** (`gemini`) as the reasoning engine, on the user's own provider
**OpenCode** (`opencode`), **pi** (`pi`), **Gemini CLI** (`gemini`), or **Qwen Code** (`qwen`) as the reasoning engine, on the user's own provider
account — the server never holds the user's provider credentials.
One daemon hosts **many independent agents** — each with its own dedicated
home directory, memory, skills, and notes. In Cumora these still appear
Expand Down Expand Up @@ -45,7 +45,7 @@ managed cloud agents and local agents into the same picture.
user to set up; it's always online.
- **Your computers** — machines you pair (your Mac, a VPS). Each runs the
`cumora agent computer` daemon with a local engine (Claude Code /
Codex / Grok Build / Cursor Agent / OpenCode / pi / Gemini CLI). Agents you place here are BYOA agents.
Codex / Grok Build / Cursor Agent / OpenCode / pi / Gemini CLI / Qwen Code). Agents you place here are BYOA agents.

```
Computers
Expand Down Expand Up @@ -194,13 +194,13 @@ from their own agenda — Kanban cards and due calendar slots — via
## Engine integration

`server/src/agents/computer/engine.ts` defines one `EngineAdapter` per
engine (`claude`, `codex`, `grok`, `cursor`, `opencode`, `gemini`). Persistent per-agent
engine (`claude`, `codex`, `grok`, `cursor`, `opencode`, `gemini`, `qwen`). Persistent per-agent
sessions are preferred when the CLI exposes one; Cursor and OpenCode use
one-shot `run()` for every wake and resume the session id reported by the CLI.

```ts
interface EngineAdapter {
id: 'claude' | 'codex' | 'grok' | 'cursor' | 'opencode' | 'gemini'
id: 'claude' | 'codex' | 'grok' | 'cursor' | 'opencode' | 'gemini' | 'qwen'
seedHome(home, persona) // lay out CLAUDE.md/AGENTS.md, skills, dirs
startSession?(args): EngineSession | null // persistent session (primary)
run(args): Promise<…> // one-shot fallback
Expand All @@ -215,16 +215,16 @@ interface EngineSession {
}
```

| Concern | Claude Code | Codex CLI | Grok Build | Cursor Agent | OpenCode | pi | Gemini CLI |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Secure default | Claude Code ≥ 2.1.248 with `--restricted`; no Bash/PowerShell/web tools; host-home reads, command network, unsandboxed retry, and subprocess credentials are denied | Codex ≥ 0.138.0 with a custom permission profile: only minimal runtime reads plus the agent home; command network disabled; tool env allowlisted; user/project config, rules, hooks, apps, remote plugins, and multi-agent tools ignored or disabled | disabled | disabled | disabled | disabled | disabled |
| Platform | macOS, Linux, WSL2; native Windows disabled because Claude's sandbox is unsupported there | macOS, Linux, WSL2, native Windows | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only |
| Persistent session | secure default; `claude -p --input-format stream-json --output-format stream-json --verbose` | compatibility opt-in only; secure default uses one-shot `exec` | compatibility opt-in ACP | none | none | compatibility opt-in RPC | none |
| Standing prompt | `--append-system-prompt-file <home>/.cumora-standing-prompt.md` | inlined into each secure one-shot wake | compatibility ACP `_meta.rules` | inlined | inlined | compatibility `--append-system-prompt` | inlined |
| One-shot | sandboxed `claude -p … --output-format stream-json` | sandboxed `codex exec --ignore-user-config --ignore-rules …` | compatibility `grok -p … --always-approve` | compatibility `cursor-agent … --force --trust` | compatibility `opencode run … --auto` | compatibility `pi … -p` | compatibility `gemini … --yolo` |
| Custom argv | ignored securely; requires the compatibility opt-in | ignored securely; requires the compatibility opt-in | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required |
| Memory / persona file | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` plus `.opencode/skills/` | `AGENTS.md` plus `.pi/skills/` (loaded via `--skill`) | `GEMINI.md` plus `.gemini/skills/` |
| Triage (small brain) | restricted and tool-free | read-only custom profile and tool env | compatibility only | compatibility only | compatibility only | compatibility only | compatibility only |
| Concern | Claude Code | Codex CLI | Grok Build | Cursor Agent | OpenCode | pi | Gemini CLI | Qwen Code |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Secure default | Claude Code ≥ 2.1.248 with `--restricted`; no Bash/PowerShell/web tools; host-home reads, command network, unsandboxed retry, and subprocess credentials are denied | Codex ≥ 0.138.0 with a custom permission profile: only minimal runtime reads plus the agent home; command network disabled; tool env allowlisted; user/project config, rules, hooks, apps, remote plugins, and multi-agent tools ignored or disabled | disabled | disabled | disabled | disabled | disabled | disabled |
| Platform | macOS, Linux, WSL2; native Windows disabled because Claude's sandbox is unsupported there | macOS, Linux, WSL2, native Windows | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only | compatibility opt-in only |
| Persistent session | secure default; `claude -p --input-format stream-json --output-format stream-json --verbose` | compatibility opt-in only; secure default uses one-shot `exec` | compatibility opt-in ACP | none | none | compatibility opt-in RPC | none | none — 0.22.3 has no stream-json INPUT mode |
| Standing prompt | `--append-system-prompt-file <home>/.cumora-standing-prompt.md` | inlined into each secure one-shot wake | compatibility ACP `_meta.rules` | inlined | inlined | compatibility `--append-system-prompt` | inlined | inlined |
| One-shot | sandboxed `claude -p … --output-format stream-json` | sandboxed `codex exec --ignore-user-config --ignore-rules …` | compatibility `grok -p … --always-approve` | compatibility `cursor-agent … --force --trust` | compatibility `opencode run … --auto` | compatibility `pi … -p` | compatibility `gemini … --yolo` | compatibility `qwen --output-format stream-json --yolo` |
| Custom argv | ignored securely; requires the compatibility opt-in | ignored securely; requires the compatibility opt-in | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required | compatibility opt-in required |
| Memory / persona file | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` plus `.opencode/skills/` | `AGENTS.md` plus `.pi/skills/` (loaded via `--skill`) | `GEMINI.md` plus `.gemini/skills/` | `QWEN.md` plus `.qwen/skills/` |
| Triage (small brain) | restricted and tool-free | read-only custom profile and tool env | compatibility only | compatibility only | compatibility only | compatibility only | compatibility only | compatibility only |

Sessions carry a resume id (`~/.cumora/sessions/<agentId>.session`); a
failed resume falls back to a fresh thread instead of wedging the agent.
Expand Down Expand Up @@ -332,6 +332,7 @@ CUMORA_ENGINE_MODEL=local CUMORA_TRIAGE_MODEL=local-small cumora agent computer
.cursor/skills/ ← Cursor-native skill directory
.opencode/skills/ ← OpenCode-native skill directory
.gemini/skills/ ← Gemini-native skill directory
.qwen/skills/ ← Qwen-native skill directory
.pi/skills/ ← pi-native skill directory (via --skill)
bin/cumora ← compatibility mode only
memory/MEMORY.md ← the agent's durable memory index
Expand Down Expand Up @@ -384,7 +385,7 @@ CREATE TABLE computers (
owner_user_id TEXT, -- null for the managed Cumora Cloud row
name TEXT NOT NULL, -- "Cumora Cloud", "MacBook Pro", …
kind TEXT NOT NULL, -- 'cloud' | 'local' | 'vps'
available_engines JSONB, -- ['claude','codex','grok','cursor','opencode','pi','gemini'] (daemon-detected)
available_engines JSONB, -- ['claude','codex','grok','cursor','opencode','pi','gemini','qwen'] (daemon-detected)
status TEXT NOT NULL, -- 'online' | 'offline' | 'busy'
last_seen_at TIMESTAMP,
credential_hash TEXT, -- SHA256 of the device token
Expand Down
2 changes: 1 addition & 1 deletion scripts/guard-big-brain.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ export function lineViolations(rel, raw) {
out.push('big-brain engine spawn (adapter.run) outside the gated daemon path')
}
// R4 — a supported engine binary spawned directly, outside the adapter.
if (/(?:spawn|execFile\w*|exec)\s*\(\s*['"`](claude|codex|grok|cursor-agent|opencode|pi|gemini)['"`]/.test(code) && !ALLOW.engineSpawn.includes(rel)) {
if (/(?:spawn|execFile\w*|exec)\s*\(\s*['"`](claude|codex|grok|cursor-agent|opencode|pi|gemini|qwen)['"`]/.test(code) && !ALLOW.engineSpawn.includes(rel)) {
out.push('engine binary spawned outside the engine adapter (bypasses the classify=small / run=big split)')
}
return out
Expand Down
Loading
Loading