Source: docs/integration/environments.md

Environments

Keep Forgium Agent access, host-application endpoints, and credentials isolated

by environment. A capability registered in one environment is not a deployment

mechanism for another.

Access bundles

Request a separate bundle from the platform operator for every environment you

will use:

# Example only; use values issued by the Forgium administrator.
FORGIUM_AGENT_BASE_URL=https://<environment-public-api-host>
FORGIUM_AGENT_API_KEY=mg_<environment-key>

Never point a production host application at a development or staging API key.

Never reuse a capability endpoint token across environments unless its owning

application explicitly authorizes that use.

Environment	Intended use	Capability endpoint
Development	Local implementation and contract preparation	Local endpoint for direct tests; an authorized HTTPS tunnel is required before a deployed Worker can call it.
Staging	End-to-end verification before release	Staging HTTPS endpoint, staging credential reference, and staging Forgium Agent access bundle.
Production	Customer traffic	Production HTTPS endpoint, production credential reference, and production Forgium Agent access bundle.

Promotion workflow

Repeat the capability lifecycle in each target environment; do not copy a

staging capability ID or credential reference into production.

Deploy the host application's endpoint to the target environment and verify
its scoped-token authentication directly.
Use the target environment's FORGIUM_AGENT_* bundle to store that endpoint
token with PUT /v1/capability-credentials/{credentialRef}.
Import the target environment's manifest with its exact HTTPS URL.
Contract-test the imported capability, then activate it.
Send a real chat request to verify that the agent used the target endpoint.

See business capabilities for the manifest and API

commands.

Release safety

Before production activation, verify all of the following:

the base URL and API key belong to production;
the manifest contains the production endpoint URL and no secrets;
the endpoint accepts only its production scoped token;
the contract test passed for the current capability revision; and
a chat smoke test returns a result grounded in the production endpoint.

Staging E2E gate

The repository includes two independent generic HTTPS reference consumers and a

release-gate command:

FORGIUM_E2E_ENV=staging bun run test:e2e:staging

The command requires the explicit staging URL, API key, control token, two

consumer URLs/tokens/control tokens, and a second access-bundle key for the

isolation assertion. It rejects non-HTTPS URLs, configured production hosts,

missing inputs, and guessed defaults. It emits only a redacted report. The

consumer setup, reset, and token-rotation endpoints exist only in staging and

accept synthetic data.

Rollback

If a newly activated capability behaves incorrectly, disable it:

curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/capabilities/$CAPABILITY_ID/disable" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

Then correct the host endpoint or manifest, revise the capability, run its

contract test, and reactivate it. If the API key or endpoint token may have

leaked, notify the Forgium administrator and rotate the affected secret before

resuming traffic.