General Installation

Console process, database, object storage, and reverse proxy

Shared foundation for every executor. Backend-specific knobs live on each backend page.

Starting the Console

git clone <starforge repo> && cd starforge
uv sync
uv run forge-console serve --port 8080 --serve    # --serve binds 0.0.0.0

All configuration goes through environment variables (prefixed FORGE_) or a .env at the repo root (the root .env.example is the fully annotated template).

Core configuration

Environment variable	Description
FORGE_DEFAULT_FLEET_KIND	local | node | kuberay | slurm
FORGE_WEB_JWT_SECRET	Must be set to a fixed strong random string; the default random generation logs everyone out on restart and makes tokens non-interchangeable across replicas
FORGE_PUBLIC_URL	Externally reachable address (for OIDC callbacks / CLI authorization)
FORGE_INGEST_URL	Address training containers report metrics to; must be a console URL reachable from inside the cluster network, never 127.0.0.1
FORGE_ALLOWED_IMAGE_REGISTRIES	Comma-separated registry hosts for user --image. Empty: first-class framework overrides unrestricted, custom images rejected
FORGE_IMAGE_VERL / FORGE_IMAGE_TRL / FORGE_IMAGE_OPENRLHF	Default OCI images for those frameworks (deployment artifacts; catalog does not embed the reference)
FORGE_DB_PATH / FORGE_DB_URL	Defaults to SQLite (.forge/web.db); production can switch to PostgreSQL
FORGE_REDIS_URL	Strongly recommended for multi-replica deployments: instant token revocation, distributed rate limiting, consistency
FORGE_TIMEZONE	Service-level timezone (schedule windows and daily-report boundaries)

Object storage (MinIO / S3)

Datasets, job package distribution (required for kuberay), and artifact archiving share one setup:

FORGE_S3_ENDPOINT=https://minio.internal
FORGE_S3_ACCESS_KEY=…
FORGE_S3_SECRET_KEY=…
FORGE_S3_BUCKET=starforge

The job side only ever receives presigned URLs and never holds storage credentials.

Reverse proxy (nginx)

deploy/nginx.conf.example provides a template. Key points:

• Disable proxy buffering for /api (SSE log streaming);
• Reverse-proxy /docs to the Mintlify-hosted site (see mintlify/README.md);
• Relax WebSocket / long-connection timeouts.

Database migrations

Alembic migrations run automatically at service startup; to run them manually:

uv run alembic upgrade head

First administrator

On a fresh deployment, the first user is created via /api/auth/setup (the console’s first-visit onboarding), or added by the CLI sf admin user-add under the local account system. For OIDC integration, see Authentication and Accounts.

Before going live, run the E2E closed loop once: a single command verifies the full “submit → schedule → container → ingest” chain is configured correctly.