TunaSwarm

TunaSwarm is a local-first AI workflow simulator for freelance operations: find → profile → plan → build → verify → invoice draft → allocate. It persists workflow checkpoints, token usage, and allocation reports in local SQLite.

The default system is deliberately non-executing. It does not submit proposals, send invoices, collect payments, trade assets, purchase domains, contact platforms, or deploy applications.

Requirements

• Python 3.10 or newer
• No runtime packages beyond the Python standard library
• Node.js is optional and only provides a compatibility wrapper for the Python API

Quick start

From the repository root:

python -m unittest discover -s tests -v
python -m api.server

The local API listens on http://127.0.0.1:4123. In another terminal:

python -m orchestration.runner run-all demo-run
python -m cli.cli workflow list-runs

run-all creates a fresh local run automatically and executes all 21 registered agents in simulation mode. No PYTHONPATH setting is required.

Optional local open-source model

Proposal and project-plan drafts can use any local OpenAI-compatible server:

$env:LOCAL_LLM_BASE_URL = "http://127.0.0.1:11434/v1"
$env:LOCAL_LLM_MODEL = "gpt-oss-20b"
python -m orchestration.runner run-all local-llm-demo

The client is compatible with local Ollama, vLLM, llama.cpp, and similar servers. OpenAI documents gpt-oss as a self-hosted open-weight model: OpenAI gpt-oss documentation. Without a configured server, the workflow remains deterministic and offline.

Configuration

Copy .env.example into your environment or set variables directly. The runtime reads:

• API_HOST / API_PORT — loopback and port defaults
• TUNASWARM_DATA_DIR — local SQLite/data directory
• TUNASWARM_MAX_BODY_BYTES — API request-size limit
• ALLOWED_ORIGINS — local frontend origins
• LOCAL_LLM_BASE_URL, LOCAL_LLM_MODEL, LOCAL_LLM_API_KEY

Remote binding is refused unless TUNASWARM_ALLOW_REMOTE=true is explicitly set. Remote binding and real-money integrations are outside this verified workflow.

API endpoints

• GET /api/health
• GET /api/runs and GET /api/runs/<id>
• POST /api/runs
• POST /api/runs/<id>/complete
• GET /api/tokens/totals?project=<run_id>
• POST /api/tokens/usage
• GET/PUT /api/allocation/rules
• GET /api/allocation/history

All API writes are local SQLite/file operations with bounded JSON validation.

Tests

python -m unittest discover -s tests -v
python tests/smoke_tests.py
python -m compileall -q .

Optional development tooling is listed in requirements-dev.txt; it is not needed to run TunaSwarm.

Safety boundary

Platform adapters are fixture-backed draft generators. Trading and domain agents produce paper signals and candidates only. Billing and collection remain unverified until a human confirms external records. The cybersecurity agent does not claim a deployment or compliance certification. Review all generated content before using it outside this local environment.