Sandbox mode

What is sandbox mode?

Every AGF organisation created via the dashboard starts in sandbox mode. Sandbox mode is a server-enforced flag on the organisation record — not a separate deployment or environment.

Sandbox lets you evaluate all AGF features — agent identity, delegation, trust scoring, policy enforcement, revocation, and audit artifacts — with no credit card and no commitment.

Sandbox limits

Sandbox accounts have three hard limits enforced by the backend:

sandbox_quota_limit = 300   # max decisions per month
sandbox_agent_limit  = 2     # max active agents at once
sandbox_trial_days   = 30    # days from first activation

• The 300-decision counter uses an atomic UPSERT with a conditional WHERE clause — concurrent requests cannot race past the limit.
• The 30-day timer is set at org creation and is immutable. Toggling sandbox off and on does not reset it.
• After 30 days with no upgrade the org is suspended. No data is deleted; an admin can reactivate by going live.

API keys in sandbox

Keys generated while your org is in sandbox mode carry the agfk_test_ prefix. This is cosmetic — it helps you distinguish test keys from live keys at a glance.

The mode of every request is resolved server-side from org.is_sandbox in the database. The key prefix is never trusted as the authority for sandbox status.

# Sandbox key (generated while org.is_sandbox = true)
agfk_test_a3f8c2d...

# Live key (generated after going live)
agfk_a3f8c2d...

• If your org goes live, keys generated before the transition retain the agfk_test_ prefix cosmetically but are now live keys. Rotate them if you want live-prefixed keys.

Making decisions in sandbox

The PDP endpoint is identical in sandbox and live. Pass your sandbox API key in X-AGF-Key:

curl -X POST https://api.agentgovernancefoundation.com/v1/decide \
  -H "X-AGF-Key: agfk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "did:agf:agent-001",
    "action": { "type": "file:write", "resource": "documents/report.pdf" },
    "context": {}
  }'

{
  "decision": "ALLOW",
  "trust_score": 72,
  "artifact_id": "agt_01J...",
  "is_sandbox": true,
  "message": "Decision authorized under sandbox trial."
}

• Sandbox audit artifacts are tagged is_sandbox: true. They are stored and queryable but are not compliance-valid.
• A 429 sandbox_quota_exceeded response is returned when your 300-decision monthly limit is reached.

Federation in sandbox

Sandbox organisations can peer with other sandbox organisations via the federation layer. Cross-mode peering (sandbox ↔ live) is blocked at both the invite and accept endpoints.

This allows you to test multi-org federation scenarios end-to-end within a sandbox environment, without polluting live registries.

• The tier gate for federation is bypassed for sandbox orgs — you do not need an enterprise subscription to test federation.

Trial expiry

Sandbox orgs that have not upgraded after 30 days are automatically suspended by a daily background job. Suspended orgs receive a 403 sandbox_expired on all API requests.

The timer is based on sandbox_first_activated_at (set once at org creation). It cannot be reset by toggling sandbox off and on.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "sandbox_expired",
  "message": "Your sandbox trial has ended. Contact your admin to go live."
}

• No data is deleted when an org is suspended. An AGF administrator can reactivate the org by going live.

Going live

An AGF administrator can toggle an org from sandbox to live via the admin panel (PATCH /admin/organizations/{org_id} with is_sandbox: false). When toggling:

• All cross-mode federation trusts are automatically revoked.

• sandbox_expires_at is cleared.

• The org's tier and existing agents, policies, and config carry over unchanged.

• Billing is NOT automatically activated. An admin must configure the billing provider and the user must complete checkout to start a paid subscription.