Agents template
A production-ready foundation where agents build reliable software instead of rebuilding the stack.
Why the foundation matters
Agents follow the patterns around them. Crucible starts every project with a disciplined application stack, durable agent runtime, deployment path, and repository guidance, so generated changes begin inside production-ready boundaries instead of a blank repository.
What it includes
The foundation is one connected system, not a menu of packages. Each layer gives the agents working on top of it a stronger production boundary.
- Application foundation
- React, TypeScript, Vite, Tailwind, and Ciridae UI on the frontend
- FastAPI, SQLAlchemy, and Alembic on the backend
- Postgres, object storage, auth, and deployment infrastructure
- Agent runtime
- Agents built on the OpenAI Agents SDK
- Temporal workflows keep long-running agent work durable across retries and restarts
- A dedicated worker polls Temporal and runs agent activities, including model calls and sandbox tool work
- Redis carries chat control messages and stream fanout
- Postgres stores threads, transcripts, queued messages, and sandbox sessions
- Model and sandbox path
- The backend exposes authenticated chat APIs, starts agent workflows in Temporal, and streams events to the frontend
- LLM Gateway routes model calls and applies fallback policy
- Each chat thread gets its own sandbox session for tool work
- Runtime surfaces
- Docker Compose starts Postgres, backend, frontend, worker, Temporal, and Redis together
- Workspaces and lite deployments use the same Compose-based startup contract
- Full deployments provision the application, worker, data, network, and observability path
- Repository guidance
AGENTS.mdandREVIEW.mdfiles throughout the repository tell agents and reviewers how each area works- Agent skills under
skills/ - GitHub Actions checks for code quality, OpenAPI and API client drift, and database tests
Work locally
Open Work locally to copy the managed environment values and start the full application and agent runtime together through Docker Compose.
Plan private network ranges
If a full deployment will connect to another network, choose its private address space before the first deployment. Each environment needs ranges that do not overlap existing or planned peers, VPN routes, on-premises networks, or other environments. That includes the cluster's internal pod and Kubernetes Service ranges, even though they are not advertised as peer routes. Renumbering after provisioning can require replacing network resources.
Sizes are total IPv4 addresses. Cloud providers reserve some addresses inside each subnet, so the usable count is lower.
- Network and data ranges: The defaults are app subnet
10.0.0.0/24(256 addresses), GKE nodes10.2.0.0/24(256), and backend connector10.8.0.0/28(16). Cloud SQL private service access also requires a separate/16(65,536). - Cluster-internal ranges: GKE uses
10.4.0.0/14(262,144 addresses) for pods and10.9.0.0/20(4,096) for Kubernetes Services. Cloud NAT keeps these ranges off public internet egress, but they still must not overlap connected networks: cluster routing can intercept a matching destination, and pod addresses can remain unmasqueraded on private traffic. - Allocation guidance: Reserve a unique contiguous
/13or larger parent block per environment, then carve all six ranges from it. A/13is a planning recommendation, not a provider requirement. The Terraform module lets Google choose the Cloud SQL/16automatically; deterministic peering plans should pin that address before the first apply. The generated environment root does not expose the remaining CIDR settings, so thread custom ranges through the environment, deployment, and VPC modules.