Status: v0 integration architecture
Date: 2026-08-28
Project cost target: USD 0 for the bootstrap path
Connect IDKMesh to useful free compute and free/volunteer agents without coupling the project to one provider and without giving an external worker repository authority.
The resource layer is deliberately split into two independent concerns:
resource discovery / planning
|
v
bounded Work Unit
|
v
worker or compute offer
|
v
candidate result
|
v
independent verification
|
v
human / governance decision
A free resource is capacity, not authority.
Free tiers change, services disappear, quotas move, and volunteer machines are intermittent. IDKMesh therefore models every external resource as an expiring evidence-backed offer.
Each offer records:
repo_write_authority=false and merge_authority=false in v0.examples/resources/free-resource-registry-v0.1.json is the current registry. scripts/free_resource_planner.py fails closed when an offer is stale or incompatible.
GitHub
|
+------------+------------+
| |
v v
Free Resource Planner canonical Work Unit
(read-only Actions) |
| |
+------------+-------------+
|
+---------------+------------------+
| | |
v v v
GitHub Actions hosted agent volunteer node
free public CI (opt-in) (opt-in)
| | |
deterministic Jules / Ollama / goose /
compute/tests Gemini OpenHands / future
| | |
+---------------+------------------+
|
v
untrusted candidate/evidence
|
v
canonical independent verification
|
v
explicit human decision
For a public repository, standard GitHub-hosted runners are the best bootstrap compute pool because they can run deterministic CI, tests, simulations, schema checks, benchmark shards, and evidence tooling without project-paid compute.
IDKMesh should use this lane aggressively for verification and deterministic compute, not for burning LLM tokens.
Current integration:
.github/workflows/free-resource-plan.yml;permissions: contents: read;The Gemini Developer API currently exposes a free tier for some models. Treat the quota as opportunistic, not guaranteed infrastructure.
If the repository owner wants this lane:
GEMINI_API_KEY;workflow_dispatch advisory workflow first;main, not untrusted PR-head code;contents: read, do not persist checkout credentials;google-github-actions/run-gemini-cli to reviewed immutable SHA f77273f4c914e4bf38440cf36a0369cb64a37489 (v0.1.22 at time of review);The action is intentionally not activated automatically in v0. Zero price is not a reason to weaken the trust boundary.
Jules can be connected to GitHub and currently provides a bounded free plan. Use it as a contributor-like coding lane:
issue / Work Unit
-> human selects bounded task
-> Jules works in its environment
-> proposed diff / PR
-> normal IDKMesh verification
Do not encode Jules quotas as a permanent architectural constant. The registry carries a freshness deadline for this reason.
This is the most important path for genuinely distributed zero-project-cost AI compute.
A contributor can donate idle CPU/GPU and electricity while the project supplies only bounded public Work Units.
Recommended stack:
idkmesh-node
-> disposable sandbox
-> exact repository revision
-> goose adapter
-> Ollama local tool-calling model
-> ResultManifest + patch/log evidence
-> independent verifier
Ollama keeps model inference local. goose provides an agent loop above the model. Neither worker receives GitHub merge authority.
This lane should wait for the canonical idkmesh-node PR #91 to receive its required independent human review/integration rather than creating a second worker implementation.
Self-hosted OpenHands/Agent Canvas can run coding agents on contributor-controlled infrastructure. It is useful for volunteers with a dedicated machine or VM, but it has a larger attack surface and setup cost than a minimal node adapter.
IDKMesh should integrate it as an adapter behind the same Work Unit / ResultManifest boundary, never as an all-powerful repository bot.
Personal GitHub Free accounts currently include a monthly Codespaces allowance. This is useful for onboarding contributors who do not want to configure a local environment.
It is a personal quota, not a project compute pool. IDKMesh must not automate quota farming or treat personal free allowances as guaranteed project infrastructure.
A serverless free tier such as Cloudflare Workers can eventually provide a small HTTP ingress, capability directory, or broker front door. Its free CPU budget is appropriate for routing/metadata, not coding-agent execution.
Do not add a separate broker service until GitHub-backed Work Unit pickup proves that one is needed.
GitHub Models was retired on 2026-07-30. It remains in the registry as excluded so future contributors do not accidentally revive stale architecture around it.
Do not expose normal volunteer laptops/desktops as unrestricted self-hosted Actions runners for this public repository.
The safe distinction is:
UNSAFE default
public GitHub event -> arbitrary repository code -> volunteer runner host
IDKMesh design
approved immutable Work Unit -> disposable sandbox -> bounded task -> evidence -> cleanup
A volunteer computer must distrust the task stream just as IDKMesh distrusts worker output.
The project must not evade quotas, create accounts to multiply free allowances, mine cryptocurrency, run unrelated workloads, or disguise automated workloads as interactive use. A resource disappears from the eligible registry when its terms, quota, security, or availability no longer fit.
free_resource_planner.py first applies hard gates:
eligible(r, t) =
zero_project_cost
AND source_evidence_fresh
AND task_class_supported
AND required_capabilities_present
AND public_data_only
AND no_repo_write_required
AND user_consented_to_secret_if_needed
AND user_consented_to_external_processing_if_needed
AND no_merge_authority
Only eligible offers are ranked. The v0 score rewards availability, capability fit, independence, and low credential/external-processing exposure while penalizing setup burden, scarcity, and security risk.
The score is scheduling advice, never correctness evidence.
Use GitHub Actions to shard:
After explicit owner setup:
Do not activate repository writes simply because a hosted agent is free.
After canonical node integration:
Use GitHub as the first broker:
approved issue / checked-in Work Unit
-> read-only discovery
-> node claims lease
-> executes locally
-> uploads candidate through a constrained contribution path
-> verifier evaluates
-> human integrates or rejects
Only if this becomes a bottleneck should IDKMesh add a native broker/service.
Do not measure success by number of agents or free CPU-hours consumed. Measure:
The shortest safe path is:
GitHub Actions (now)
+ optional hosted advisory agents
+ canonical idkmesh-node
+ volunteer local-model adapters
+ independent verifier
= Free Resource Mesh
The system should grow by adding resource offers and adapters, not by granting more authority to workers.