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.

1. Deploy the host application's endpoint to the target environment and verify

its scoped-token authentication directly.

1. Use the target environment's FORGIUM_AGENT_* bundle to store that endpoint

token with PUT /v1/capability-credentials/{credentialRef}.

1. Import the target environment's manifest with its exact HTTPS URL.
2. Contract-test the imported capability, then activate it.
3. 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.

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.