Skip to content

Infrastructure & Operations Specification

This document details the environment requirements, configuration, and storage paths for deploying Farmercode components.

1. Environment Variables

These variables must be injected into the Worker and Middleware environments.

Variable Component Description
FARMERCODE_S3_BUCKET Executor Target S3 bucket for telemetry.
FARMERCODE_S3_REGION Executor AWS Region for S3.
AWS_ACCESS_KEY_ID Executor AWS Credentials for S3 Sync.
AWS_SECRET_ACCESS_KEY Executor AWS Credentials for S3 Sync.
GITHUB_TOKEN Executor PAT for git operations (Clone/Push).
ANTHROPIC_API_KEY Executor For Claude SDK.
GITHUB_WEBHOOK_SECRET GitHub Middleware For validating webhook signatures.
GITHUB_APP_CREDS_JSON GitHub Middleware JSON map of {agent_name: {app_id, private_key}}.

2. Worker Runtime Requirements

The Docker image or host environment for the Temporal Worker must include:

  • Python 3.10+
  • Git: Required for cloning repos and git archive operations.
  • AWS CLI: Required for the "Universal Eager Sync" (aws s3 sync).
  • Subprocess Permission: The Worker must be allowed to spawn subprocesses (for git and prompt generation scripts).

3. Storage Strategy

Path Resolution

Since Workers are stateless, they set up their environment dynamically at the start of each Activity.

  • $PROJECT_ROOT: The working directory where the target repository (farmer1st-stack) is cloned/checked out.
  • $FARMERSPEC_PATH: Resolved to $PROJECT_ROOT/.farmerspec/ (Embedded Prompts).

Telemetry Structure (S3)

All artifact data is stored in S3 to keep git repositories clean.

s3://{bucket}/runs/{run_id}/
├── result.json
├── prompts/ -> (Symlink/Copy of specific farmerspec version)
└── phases/{sequence}_{phase_name}/
    └── attempt_{n}/
        ├── message.json      # Input
        ├── response.json     # Raw LLM response
        ├── result.json       # Parsed Output
        ├── feedback.json     # RL Data
        ├── execution.json    # Metadata (duration, cost)
        └── usage.json        # Token usage

4. GitHub Middleware Hosting

  • Type: Stateless FastAPI Service.
  • Network: Must be publicly reachable (for GitHub Webhooks).
  • Security: HMAC signature validation required on all requests.