Reference preview

These pages describe Fibric’s target architecture. Public CLI, API, SDK, and sandbox access are not available. Examples do not establish deployed capabilities.

Platform

Environments

The reference environment model distinguishes sandbox connectors, workspaces within a tenant, and separate tenants. Capability bindings determine which source or target system an operator uses.

#Three levels of separation

Level	Mechanism	What it separates	Use it for
Sandbox connectors	Connectors such as `sandbox-orders` that speak the same capability interface as a real system but act on a simulated one.	Side effects. Everything else, envelopes, plans, the trust gate, receipts, runs exactly as in production.	Developing operators, demos, the quickstart.
Workspaces	`workspace_id` on envelopes and rows; operators, views, and stream filters scoped to a workspace.	Work, organizationally, within one tenant. Not a security boundary.	Staging inside the same tenant, per-team or per-site partitions.
Separate tenants	A second tenant, with its own API keys, connector installations, credentials, and Postgres row-level security wall.	Everything. Two tenants share hardware and nothing else; see Tenancy & isolation.	Hard production/non-production separation, compliance boundaries, per-client isolation for resellers.

A staging workspace can bind capabilities to test connectors while a production workspace binds them to live sources. Use separate tenants when the environments require separate security boundaries.

#The sandbox is the same machinery

A sandbox connector is not a mock of Fibric; it is a real connector whose tools act on a simulated system. The governed loop is identical: the operator proposes, the trust gate disposes, single-flight and idempotency apply, and every action is receipted. This matters because what you are testing in an agentic system is mostly not the side effect itself; it is the proposals your operator makes and the policy that gates them, and both are exercised fully against a sandbox.

bash

# bind the orders capability role to the sandbox
fibric connectors add sandbox-orders --as orders

$ fibric connectors list
ROLE     CONNECTOR        STATUS
orders   sandbox-orders   ready

# the operator, its trigger, and its guardrails are written against "orders",
# with no knowledge of which connector stands behind the role

Sandbox connectors declare auth: none(), so no real credential exists in the sandbox path at all, the strongest possible form of key separation for development. For repeatable local testing against recorded traffic, fibric dev replay re-runs event fixtures through your operator; see Testing connectors and the CLI reference.

#Workspaces as environment boundaries

A workspace is a tenant-scoped partition: workspace_id travels on every envelope and every row, and operators, event queries, and stream subscriptions can all be scoped to one. Using workspaces as environments means your staging traffic and production traffic live in the same tenant but never mingle in a view, a trigger, or a consumer:

Ingest staging events with the staging workspace_id; operators registered in that workspace see only them.
Filter dashboards and stream consumers by workspace_id, so a staging burst never pollutes a production chart.
Receipts carry the workspace, so an audit of production actions excludes rehearsals cleanly.

A workspace is not a wall

Tenant-scoped database access provides the security boundary. Workspaces organize data and work inside a tenant; they do not establish an independent tenant boundary.

#Promoting configuration

Because operators request capabilities rather than naming connectors, promotion is a rebinding, not a rewrite. The operator definition, its trigger, its prompt, and its guardrails are byte-identical in both environments; the only thing that changes is which connector fulfills each capability role.

promotion checklist

1. connectors   install the real connector and bind it to the same role
                  fibric connectors add cn-magento --as orders
                verify:  fibric connectors test orders
2. guardrails   review policies against real value: maxValue ceilings,
                which tools ALERT. Tighten before first production run;
                loosen later with evidence from receipts.
3. operator     create/resume the operator in the production workspace,
                same definition, same trigger
4. watch        fibric receipts tail — confirm first dispositions look right
5. rollback     fibric operators pause <id> stops new proposals instantly;
                already-executed actions are receipted and, where the tool
                declares an inverse, undoable

Step 2 deserves the emphasis. The sandbox will happily approve a $10,000 refund because sandbox money is free; production guardrails should make that an ALERT or a BLOCK. A sound pattern for a newly promoted operator is to set ALERT on every side-effecting tool for the first week, approve through the Actions & plans API or console, and convert to ALLOW per tool as the receipt history earns it. Trust is granted with evidence, not assumed with deployment.

#Key separation

Environment separation is only as good as the separation of the secrets that reach each environment.

Practice	Why
Issue distinct API keys per environment and per consumer	Keys are revocable individually. A leaked staging key is revoked without rotating production consumers, and receipts and request logs attribute traffic to the key that sent it.
Never point a staging key at production configuration in CI	Keep `FIBRIC_API_KEY` per environment in your CI secret store, not in a shared default. All keys are tenant-scoped; in a two-tenant setup this separation is structural rather than procedural.
Use sandbox connectors (`auth: none()`) below production	The strongest credential separation is a path with no credential in it. Where staging must hit a real system, grant it that system's staging credentials, never production ones.
Rotate on promotion boundaries	When an operator graduates and its human owners change, rotate the connector credentials it depends on; the zero-downtime sequence is in Secrets and credentials.

Workspace-scoped keys

API keys authenticate as a tenant. Restricting a key to a single workspace, so a staging key structurally cannot write production-workspace events within the same tenant, is in preview; until it is generally available, treat workspace discipline within one tenant as procedural, and use two tenants where the restriction must be structural.

See tenancy for customer separation, secrets for credential handling, and the quickstart preview for a reference walkthrough.