A self-contained OpenCode configuration that doubles as a git repository. Clone it once — get a fully autonomous multi-agent coding environment with containerized execution, lint pipelines, and a hub-and-spoke agent workflow.
Everything runs inside a Podman container. No language toolchains, no npm, no pip — just Podman and git on the host.
The container reuses your host's OpenCode data directory (~/.local/share/opencode) as the source of truth for API keys and credentials.
Scenario A (Recommended): Install OpenCode on the host
# Install opencode CLI on the host
curl -fsSL https://opencode.ai/install.sh | bash
# Set up your API keys once
opencode config
# Verify
opencode --versionYour credentials are usable both on the host and inside the container — no duplication.
Scenario B: No host OpenCode
You can skip the host install, but you will need to re-enter API keys inside each container session (the container runs with --rm, so nothing persists). Not recommended.
# 1. Clone anywhere
git clone https://github.com/anomalyco/opencode-factory ~/path/to/opencode-factory
# 2. Optional: add to PATH for convenience
echo 'export PATH="$PATH:$HOME/path/to/opencode-factory/bin"' >> ~/.bashrc
source ~/.bashrc
# 3. Navigate to your project and run
cd ~/my-project
autoopencodeThe first run builds the container image (one-time ~2GB download). Subsequent runs launch instantly.
autoopencode # Interactive mode (opencode --auto)
autoopencode run # Non-interactive mode (opencode run --auto)
autoopencode run "task" # Pass a task directly Host machine Container (--rm)
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ │ │ │
│ ~/path/to/opencode-factory │────▶│ /home/vscode/.config/opencode│
│ (config, agents, scripts) │ │ │
│ │ │ │
│ ~/.local/share/opencode │────▶│ /home/vscode/.local/share/ │
│ (API keys, DB, MCP servers) │ │ opencode │
│ │ │ │
│ $(pwd) — your project │────▶│ /workspace │
│ │ │ │
│ │ │ opencode CLI + python + node│
│ │ │ + uv + oc-* scripts │
└──────────────────────────────┘ └──────────────────────────────┘
Three volumes are mounted:
| Host path | Container path | Purpose |
|---|---|---|
| This repo clone | /home/vscode/.config/opencode |
Agents, models, scripts, AGENTS.md |
~/.local/share/opencode |
/home/vscode/.local/share/opencode |
Credentials. API keys, MCP server configs, session state |
$(pwd) |
/workspace |
Your project code |
The container is ephemeral (--rm). Only your host project files and OpenCode data persist.
- Podman: Container runtime (Docker not tested;
--userns=keep-idis Podman-specific) - bash: All scripts are bash-based
- Git: For cloning the repository
- Disk space: ~2 GB for the container image
- OpenCode on host (recommended): For API key setup. See Prerequisites.
Linux: Fully supported. Tested on Kubuntu 26.04.
macOS: Not supported. While Podman runs on macOS via podman machine, the entry script uses Linux-specific features (--userns=keep-id). Would require modifications.
Windows: Not supported. Requires WSL2.
.
├── AGENTS.md # Global instructions loaded by all agents
├── Dockerfile # Container image (Python 3.12, Node 20, opencode CLI, uv)
├── opencode.jsonc # OpenCode config: providers, agents, defaults
├── agents/
│ ├── TechLead.md # Primary orchestrator (requirement & feasibility gate)
│ ├── Architect.md # System design, produces implementation_plan.md
│ ├── Engineer.md # Core implementation
│ ├── QA.md # Tests, docs, validation
│ └── Utility Engineer.md # Boilerplate, schemas, helpers
├── bin/
│ └── autoopencode # Entry point: auto-detects its location, builds image, launches opencode
├── scripts/
│ ├── oc-env-check # Verify Python, uv, disk space, workspace
│ ├── oc-bootstrap # Create .venv, install dev dependencies
│ ├── oc-lint # ruff + isort --check-only + mypy
│ ├── oc-fix # Auto-fix lint issues
│ ├── oc-test # pytest with coverage
│ ├── oc-precommit # Full gate: debug prints, secrets, shebangs, lint
│ └── oc-pip # Safe pip install wrapper
├── fabric_tests/
│ └── techlead_example.md # Real session transcript (TechLead feasibility gate demo)
├── .gitignore
└── README.MD
| Agent | Model | Role |
|---|---|---|
| TechLead | DeepSeek V4 Pro | Primary orchestrator. Validates requirements, challenges assumptions, runs feasibility gates, delegates execution. Never writes code. |
| Architect | DeepSeek V4 Pro | Reads approved_spec.md, produces implementation_plan.md. Focuses on system design and module boundaries. |
| Engineer | DeepSeek V4 Pro | Implements core modules based on the architecture plan. Runs lint before handoff. |
| QA | DeepSeek V4 Flash | Writes tests, runs oc-precommit && oc-test. Reports failures back to TechLead (max 3 retries). |
| Utility Engineer | DeepSeek V4 Flash | Fast boilerplate generation: Pydantic schemas, wrappers, helpers. |
User → TechLead → Architect → TechLead → Engineer → TechLead → QA → Done
↑ ↓
└── retry (≤3) ─┘
- TechLead asks clarifying questions, runs Technical Feasibility Gate, produces
approved_spec.md. - Architect produces
implementation_plan.md. - Engineer implements, optionally delegates boilerplate to Utility Engineer.
- QA writes tests, runs validation. On failure → TechLead re-invokes Engineer (max 3 cycles).
- TechLead verifies all gates pass and completes the session.
Stop rule: oc-precommit exits 0 AND oc-test exits 0.
All scripts are available at /opt/oc-scripts inside the container (in $PATH).
| Script | Purpose |
|---|---|
oc-env-check |
Verify Python, uv, disk space, workspace writability |
oc-bootstrap |
Create .venv and install project dev dependencies |
oc-lint |
Run ruff, isort --check-only, mypy |
oc-fix |
Auto-fix lint issues (ruff --fix, isort) |
oc-test |
Run pytest with coverage (default threshold: 70%) |
oc-precommit |
Full gate: debug prints, secrets scan, shebangs, lint |
oc-pip |
Safe pip install wrapper (always adds --no-cache-dir) |
autoopencode auto-detects its own location — the repo can be cloned anywhere. You can override paths via environment variables:
| Variable | Default | Description |
|---|---|---|
OPENCODE_CONFIG_DIR |
Auto-detected from script location | Path to this repo clone |
OPENCODE_DATA_DIR |
~/.local/share/opencode |
Host OpenCode data directory |
# Example: custom data directory
OPENCODE_DATA_DIR=/some/other/path autoopencodeTo change the container image name, set the IMAGE_NAME variable in the script.
The file fabric_tests/techlead_example.md contains a full transcript of TechLead responding to a task: creating a script to update icons in Firefox (Snap) bookmarks.
The trap is that a direct solution to this problem either does not exist, or requires inventing crutches disproportionate to the task's importance. The previous version only recommended reading the sources, which led to the false conclusion "everything is fine, we are working." The current version worked better — it directly forced reading 23 sites. However, TechLead still did not abandon the idea of direct intervention, leaving this option on the list with many caveats.
Transcript: fabric_tests/techlead_example.md
The following are intentionally gitignored because they are auto-generated by OpenCode at runtime and should not be tracked:
node_modules/— created by OpenCode when installing pluginspackage.json/package-lock.json/bun.lock— generated by OpenCode's plugin system