core-lead/molecule-core
1
0
Fork 0
forked from molecule-ai/molecule-core
Code Pull Requests Activity
ff5149b7df
molecule-core/docs/development/local-development.md
Hongming Wang 24fec62d7f initial commit — Molecule AI platform 
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1)
with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo.

Brand: Starfire → Molecule AI.
Slug: starfire / agent-molecule → molecule.
Env vars: STARFIRE_* → MOLECULE_*.
Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform.
Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent.
DB: agentmolecule → molecule.

History truncated; see public repo for prior commits and contributor
attribution. Verified green: go test -race ./... (platform), pytest
(workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:55:37 -07:00

4.4 KiB
Raw Blame History

Local Development

Starting the Stack

docker compose up

This starts:

Service Port Description
Postgres internal only Primary database
Redis internal only Ephemeral state
Platform (Go) :8080 Control plane API
Canvas (Next.js) :3000 Visual frontend
Langfuse web :3001 (host) / :3000 (internal) Observability UI
Langfuse worker — Background processing
ClickHouse — Langfuse dependency

Each workspace container is provisioned on demand by the platform when a user creates or imports one.

Langfuse uses a dedicated langfuse Postgres database. The compose stack creates it automatically before starting the Langfuse service, so it does not conflict with the platform's molecule schema.

Infrastructure Only

To start just Postgres, Redis, and Langfuse (no application code):

docker compose -f docker-compose.infra.yml up

Optional Profiles

docker compose --profile multi-provider up  # Add LiteLLM proxy (unified LLM API)
docker compose --profile local-models up    # Add Ollama (local LLM models)

Environment Variables

Platform (Go)

DATABASE_URL=postgres://dev:dev@postgres:5432/molecule?sslmode=prefer
REDIS_URL=redis://redis:6379
PORT=8080
SECRETS_ENCRYPTION_KEY=dev-key-change-in-production
WORKSPACE_DIR=/path/to/molecule-monorepo   # Optional global fallback; prefer per-workspace workspace_dir in org.yaml or API

Canvas (Next.js)

NEXT_PUBLIC_PLATFORM_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080/ws

Workspace Runtime

WORKSPACE_ID=           # assigned by platform on provision
WORKSPACE_CONFIG_PATH=  # path to config folder inside container
MODEL_PROVIDER=         # e.g. anthropic:claude-sonnet-4-6
TIER=                   # 1, 2, 3, or 4
PLATFORM_URL=           # http://platform:8080
PARENT_ID=              # set by platform during team expansion (empty for top-level)
ANTHROPIC_API_KEY=      # or OPENAI_API_KEY, etc.
LANGFUSE_HOST=          # http://langfuse-web:3000 (internal container port; host-mapped to :3001)
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGSMITH_TRACING=true  # LangGraph reads this to enable tracing

Technology Versions

Go              1.25+ (go.mod)
Python          3.11+
Node.js         22+
Next.js         15
React Flow      12   (@xyflow/react)
a2a-sdk         0.3+ (A2A server SDK, install with a2a-sdk[http-server])
langfuse        3.x  (self-hosted Docker)
Postgres        16
Redis           7
Docker Compose  2.x

Running Tests

Unit Tests

cd platform && go test -race ./...               # Go tests with race detection (358 tests)
cd canvas && npm test                            # Vitest tests (188 tests)
cd workspace-template && python -m pytest -v     # Workspace runtime tests (148 tests)

Integration Tests

bash test_api.sh             # 62 API tests (requires platform running)
bash test_a2a_e2e.sh         # 22 A2A e2e tests (requires platform + 2 agents)
bash test_activity_e2e.sh    # 25 activity/task E2E tests (requires platform + 1 agent)

CI Pipeline

GitHub Actions runs automatically on push to main and on PRs (.github/workflows/ci.yml):

  • platform-build — Go build, vet, go test -race with coverage profiling (25% baseline threshold)
  • canvas-build — npm build, vitest run (no --passWithNoTests -- tests must exist and pass)
  • mcp-server-build — npm build
  • python-lint — pytest --cov=. --cov-report=term-missing (pytest-cov enabled)

Postgres and Redis are not exposed to the host -- use docker compose exec postgres psql or docker compose exec redis redis-cli for direct access.

Utility Scripts

Script Purpose
infra/scripts/setup.sh Initialize the local environment
infra/scripts/nuke.sh Tear down and clean up everything
bundle-compile.sh Compile workspace config folders into .bundle.json files
test_api.sh Run 62 platform API integration tests
test_a2a_e2e.sh Run 22 A2A end-to-end tests
test_activity_e2e.sh Run 25 activity/task E2E tests
setup-org.sh Create default 15-agent org hierarchy (PM + Marketing/Research/Dev teams, all Claude Code)

Related Docs