Local Development
This guide is for engineers working on AxonFlow locally or building against a self-hosted community stack while trying it.
The goal is not just to "make containers start." It is to get a reliable local environment where you can:
- build and test SDK integrations
- validate policy behavior
- exercise proxy, gateway, MCP, MAP, and WCP flows
- observe the platform with Prometheus and Grafana while you develop
Prerequisites
| Dependency | Minimum Version | Why it matters |
|---|---|---|
| Go | 1.25+ | Build and test the Go services |
| Node.js | 18+ | Build docs and any frontend/customer-portal development surfaces |
| Docker | 24+ | Container runtime for the local stack |
| Docker Compose | v2 | Standard local platform startup path |
| Git | 2.30+ | Clone, branch, and inspect the repo |
The Current Local-Dev Model
The default local stack runs in community deployment mode:
export DEPLOYMENT_MODE=community
That is the current, supported local-development path. In this mode:
- license validation is bypassed
- request auth is relaxed for the local developer flow
- community limits and community build paths apply
- enterprise-only build-gated features still do not appear magically
This is important because older references to SELF_HOSTED_MODE are no longer the main docs path. The current compose stack and current platform docs should steer engineers toward DEPLOYMENT_MODE=community.
Quick Start With Docker Compose
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow
cp .env.example .env
# Add at least one provider key if you want routed LLM features:
# OPENAI_API_KEY=...
# or ANTHROPIC_API_KEY=...
docker compose up -d
docker compose ps
The default local compose file already sets:
DEPLOYMENT_MODE=community- Agent on
:8080 - Orchestrator on
:8081 - Grafana on
:3000 - Prometheus on
:9090
Verifying The Local Stack
curl -s http://localhost:8080/health | jq .
curl -s http://localhost:8081/health | jq .
curl -s http://localhost:8080/prometheus | head
curl -s http://localhost:3000/api/health
You want to confirm more than "container is running." A strong local check includes:
- both health endpoints return healthy service metadata
- Prometheus metrics are exposed on
/prometheus - Grafana is reachable on
:3000 - the compose services report healthy, not just started
Build From Source
If you are changing platform code instead of only consuming the local stack, build from source:
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow
go build ./platform/...
go test ./platform/... -cover
You can still use Docker Compose for the backing services while iterating on code.
What Community Mode Does And Does Not Do
Community local development is intentionally friction-light, but it is not "everything unlocked."
What it gives you
- no license key needed for local development
- a fast path to test governed requests and workflows
- a realistic community runtime for SDK and policy iteration
- default observability via Prometheus and Grafana
What it does not give you
- enterprise-only build-gated connectors or modules
- enterprise portal experiences
- enterprise identity or compliance operating surfaces
- unlimited feature access across all tiers
That distinction matters because a lot of teams try AxonFlow in Community first, then decide whether Evaluation or Enterprise is justified once the workflows become more serious.
Useful Local Workflows
1. SDK Integration Work
Use the local stack to test:
proxyLLMCall/proxy_llm_call- MCP query flows
- workflow creation and step gating
- policy testing endpoints
2. Policy Development
Local development is a strong place to:
- create and revise tenant policies
- test regexes before rollout
- validate block, warn, redact, or
require_approvalbehavior
3. Observability Validation
Before a team trusts the platform, they usually want to see:
- latency move in Grafana
- blocked requests show up in metrics
- connector errors show up where operators can inspect them
That is all possible in the local compose stack.
Running Tests
go test ./...
go test -cover ./...
go test ./platform/agent/...
For docs, SDK, or frontend-related work in the docs repo, the same local stack is useful as the governed backend while you validate examples or integration snippets.
Hot Reload For Service Development
If you are iterating on Go services directly, use air:
go install github.com/air-verse/air@latest
cd platform/agent
air
This is helpful when you are changing handlers, policy logic, or request processing and do not want to rebuild manually on every edit.
Common Local Pitfalls
Wrong Mental Model For Auth
In community local mode, auth is relaxed for the developer flow. That is useful when trying it, but it should not be described as "production auth behavior." As soon as you leave this mode, credentials and tier behavior matter again.
Wrong Port Assumptions
The local compose defaults are:
- Agent:
8080 - Orchestrator:
8081 - Grafana:
3000 - Prometheus:
9090
If a page still tells you Grafana is on 3001, that is the wrong local community story.
Expecting Enterprise Features In Community
Community is excellent for real engineering review, but it is still Community. If a feature is build-gated or explicitly documented as evaluation-tier or enterprise-only, local community mode is not supposed to bypass that boundary.
Troubleshooting
Health Checks Fail
docker compose ps
docker compose logs axonflow-agent
docker compose logs axonflow-orchestrator
docker compose logs postgres
Port Conflicts
lsof -i :8080
lsof -i :8081
lsof -i :3000
Database Connectivity Problems
docker compose exec postgres psql -U axonflow -d axonflow -c '\l'
Rebuild Cleanly
docker compose down
docker compose up --build
If you need a full reset:
docker compose down -v
Transitioning Beyond Local Development
A typical path looks like:
- start in Community local mode
- validate policies, connectors, and workflow patterns
- move to Evaluation when higher limits or richer governance workflows matter
- move to Enterprise when the platform needs company-grade identity, compliance, and operational guarantees
