Documents are loading...

Getting Started

Platform Production Onboarding

Portal install, service credentials, key generation, MCP connectors, runtime lanes, and agent.md / skill.md handoff

This page is the production setup checklist for a new Mirror integration.

Gateway is the single hosted entry point. Agent Security (AgentIQ Identity and Policy Engine), Assurance (Discover, Governance, and Security Intelligence), VectaX Memory/VDB, Code Security (CodePrism), MCP, and connectors all inherit the same service credential, entitlement, telemetry, and audit contract.

1. Install From The Mirror Portal

Mirror SDK artifacts are private packages. Do not install production SDKs from public npm or PyPI. Use the exact version shown in Portal. Do not hard-code package versions in customer handoffs.

# 1. Log in to your Mirror portal (partner / customer credentials required)
# 2. Navigate to: Use Mirror → SDK & Quickstart
# 3. Download the TypeScript SDK tarball
 
# 4. Install locally
npm install /path/to/mirror-sdk-<version>.tgz

2. Create Service Credential

Service credentials are machine identity for hosted calls. They are not encryption keys. For new SDK users, prefer the SDK bundle download from create or rotate; it gives the SDK the URLs, credential id, license file references, and first-display secret in one local handoff.

Portal path:

  1. Open Platform Access -> Service Credentials.
  2. Create a credential for the project.
  3. Select the product profile: Gateway, VectaX/Memory, Agent Security, Assurance, Code Security, or key-management profile.
  4. Reveal client_id and client_secret once.
  5. Download the SDK bundle during create or rotate when a local SDK/agent needs the secret.
  6. Use the SDK bundle for normal clients, or exchange the credential manually only for raw HTTP automation.
export MIRROR_SERVICE_CREDENTIAL_FILE=".secrets/service-credential.json"
 
# Optional — override platform host only if the credential's gateway_url is wrong for this environment
# export MIRROR_BASE_URL="https://mirror.example.com"
# export MIRROR_API_URL="$MIRROR_BASE_URL/mapi"
# export MIRROR_GATEWAY_URL="$MIRROR_BASE_URL/gateway"
 
# Manual token exchange only when not using the SDK bundle helper (values also in the credential JSON).
# export MIRROR_TOKEN_URL="$MIRROR_BASE_URL/keycloak/realms/<your-realm>/protocol/openid-connect/token"
# export MIRROR_CLIENT_ID="<service-credential-client-id>"
# export MIRROR_CLIENT_SECRET="<service-credential-secret>"
# export MIRROR_SERVICE_CREDENTIAL_ID="<service-credential-id>"

The service-credential.json in the SDK bundle should be self-contained:

{
  "base_url": "https://mirror.example.com",
  "api_url": "https://mirror.example.com/mapi",
  "gateway_url": "https://mirror.example.com/gateway",
  "token_url": "https://mirror.example.com/keycloak/realms/<your-realm>/protocol/openid-connect/token",
  "tenant_id": "<tenant-or-enterprise-id>",
  "client_id": "<service-credential-client-id>",
  "client_secret": "<service-credential-secret>",
  "service_credential_id": "<service-credential-id>",
  "license_file": "mirror-license.json",
  "license_public_key_b64_file": "mirror-license-public-key.b64"
}

Existing credential row downloads are refresh bundles and should not reveal client_secret. Use create or rotate when a new local secret handoff is required.

Hosted routes derive tenant and project from the credential. Do not send caller-provided tenant headers in production integrations.

Before handing the bundle to an application team, run the same local verification path the SDK expects:

export MIRROR_SERVICE_CREDENTIAL_FILE=.secrets/service-credential.json
 
mirror diagnose
mirror licenses verify
mirror gateway models
mirror chat "ping"
mirror kms summary

3. Generate Keys

Key Management is the user-owned crypto surface.

Portal path:

  1. Open Platform Access -> Key Management.
  2. Generate the needed key family.
  3. Keep private key material in the browser, local SDK keystore, or customer KMS.
  4. Export only public/evaluation/search/session material to Gateway when the selected workflow requires it.
  5. Export KMS handoff metadata when operations owns wrapping or escrow.
Key familyCustody message
Encrypted computePrivate keys remain customer-owned. Gateway receives only explicit public/evaluation/bootstrap material.
PRECustomer owns private keys. Gateway may receive transform grants and public keys.
FPEUse local key custody or customer KMS references for production.
Vector/searchCustomer or Gateway-managed key reference, scoped to service credential and collection.
Session/CEKWrapped/session material only, never broad long-lived raw secrets.

4. Configure MCP And Connectors

MCP is a projection of Gateway tools. It is not a second product gateway.

Portal path:

  1. Open Gateway -> Connectors.
  2. Configure connector OAuth/config for Microsoft Graph/O365, ServiceNow, Memory, VDB, or tenant-specific adapters.
  3. Check readiness and evidence.
  4. Generate ChatGPT or Claude registration only after readiness passes.
  5. Let Gateway enforce service credential, AgentIQ Identity, Policy Engine, and audit context for all tool calls.

Useful checks:

GET /mapi/v1/gateway/mcp/summary/connectors?serviceCredentialId=<id>
GET /mapi/v1/gateway/mcp/summary/evidence?serviceCredentialId=<id>
GET /mapi/v1/gateway/mcp/registration/chatgpt?serviceCredentialId=<id>
GET /mapi/v1/gateway/mcp/registration/claude?serviceCredentialId=<id>

5. Expose Memory And VDB Through Gateway

Memory and VDB are platform capabilities behind Gateway. Do not expose a second customer-facing memory gateway.

Hosted Memory/VDB use the same service credential and bearer token as Gateway chat:

GET  /mapi/v1/gateway/mcp/vdb/collections?serviceCredentialId=<id>
POST /mapi/v1/gateway/mcp/vdb/collections
POST /mapi/v1/gateway/mcp/vdb/collections/delete
POST /mapi/v1/gateway/mcp/vdb/points/upsert
POST /mapi/v1/gateway/mcp/vdb/vector-search
POST /mapi/v1/gateway/mcp/vdb/text-search
POST /mapi/v1/gateway/mcp/memory/observe
POST /mapi/v1/gateway/mcp/memory/recall

Point get/delete and payload update are backend-native operations. Expose them only when the tenant backend enables them. The release smoke treats collection create, point upsert, vector search, text search, and collection delete as the public VDB contract.

import { Mirror } from '@mirror/sdk';
 
// Mirror() reads the service credential issued in Portal -> Use Mirror -> SDK & Quickstart
// from MIRROR_SERVICE_CREDENTIAL_FILE; the credential id binds every hosted call to
// the tenant + entitlements minted in the portal.
const client = new Mirror();
 
await client.vdb.collections.create({
  name: 'demo-docs',
  dimension: 3,
  metric: 'cosine',
  indexedFields: ['tenant_id'],
});
 
await client.vdb.points.upsert('demo-docs', {
  points: [{ id: 'doc-1', vector: [0.1, 0.2, 0.3], payload: { tenant_id: 'tenant-a' } }],
});
 
const hits = await client.vdb.search('demo-docs', {
  vector: [0.1, 0.2, 0.3],
  topK: 3,
});

Direct Memory/VDB SDKs remain valid for local/offline bundle internals, but production customer integrations should start with the hosted Gateway-backed facade.

The current release smoke treats these as the customer-facing Memory/VDB contract: collection list/create, point upsert, vector search, text search, Memory observe, and Memory recall. Backend-native point get/delete and payload update may be enabled by the tenant backend, but do not require customers to call direct Memory or VDB service URLs.

6. Select Runtime Lane

Runtime lanes are execution attributes, not separate products.

LaneUse
provider_plainexternal provider plaintext path
plainmanaged plain baseline path
protectedmanaged end-to-end encrypted runtime path
confidentialconfidential-compute protected deployment
fhe_locallocal/customer-controlled end-to-end encrypted compute flow
sdk_localoffline SDK execution

Use the Gateway runtime registry and release gates before routing a workflow to a model. Prefer the routing catalog for model and lane discovery:

GET /mapi/v1/gateway/routing/catalog?surface=gateway&includeLiveModels=false&serviceCredentialId=<id>
GET /mapi/v1/gateway/routing/catalog?surface=gateway&includeLiveModels=true&providers=bedrock,azure-openai&serviceCredentialId=<id>

Provider-specific model endpoints remain supplemental live-inventory checks. Instruction-tuned chat models must be validated through chat/messages prompt rendering, not raw completion prompts.

7. Export agent.md And skill.md

Use Mirror Builder should produce both files for handoff.

agent.md describes:

  • agent owner and identity
  • service credential profile and scopes
  • connectors/tools used
  • runtime lane and model release gate
  • guardrail and policy stages
  • Discover and Governance evidence expectations

skill.md describes:

  • Portal install command
  • required environment variables
  • SDK usage snippet
  • MCP registration payload when needed
  • key-generation requirements
  • smoke command before use

Use these files when handing a workflow to ChatGPT, Claude, IDE agents, internal agent builders, or customer SecEng.

8. Observability, Usage, And Cost

All product surfaces emit the same mirror.telemetry.v1 shape through Gateway or the hosted /mapi telemetry facade.

Required fields for usage and cost views:

  • productSurface: gateway, vectax, identity, policy, discover, governance, codeprism, sdk, portal, lms, or compliance-ingester
  • telemetryLane: trace, usage, audit, security-event, passive-analysis, or cost
  • runtimeLane: provider_plain, plain, protected, confidential, fhe_local, or sdk_local
  • inputTokens, outputTokens, totalTokens for LLM/model operations
  • billingUnit, billingQuantity, and estimatedCostUsd for cost rollups
  • serviceCredentialId in attributes for tenant-scoped filtering

Smoke events intentionally set estimatedCostUsd=0 and billingUnit=smoke_event. Real cost appears only when a live provider/runtime response includes usage data or the product emits a billable unit with a configured pricing map. If the Portal cost widget is empty, first check whether non-zero estimatedCostUsd events exist for the selected service credential and timeframe.

Useful checks:

GET /mapi/v1/observability/registry
GET /mapi/v1/observability/summary?product=gateway&serviceCredentialId=<id>
GET /mapi/v1/observability/traces?product=gateway&serviceCredentialId=<id>&pageSize=20
GET /mapi/v1/observability/passive-analysis?serviceCredentialId=<id>

9. Run Full Smoke

From the Mirror SDK workspace:

export MIRROR_API_URL="https://mirror.example.com/mapi"
export MIRROR_SERVICE_CREDENTIAL_FILE=".secrets/service-credential.json"
export MIRROR_TELEMETRY_API_URL="$MIRROR_API_URL"
export MIRROR_REQUIRE_OBSERVABILITY_PRODUCT_SMOKE=1
python3 scripts/smoke/platform_full_surface_smoke.py

Full optional customer-facing coverage adds Portal, LMS, Memory/VDB, Governance evidence ingestion, Compliance ingester, and local SDK tests. It still uses the hosted /mapi surface; it does not require a direct runtime access.

export MIRROR_VDB_COLLECTION="<collection>"
export MIRROR_GOVERNANCE_RUN_ID="<run-id>"
export MIRROR_ENABLE_MUTATING_SMOKES=1
export MIRROR_RUN_VDB_MUTATING_SMOKES=1
export MIRROR_RUN_KEYMGMT_MUTATING_SMOKES=1
export MIRROR_PORTAL_URL="https://mirror.example.com"
export MIRROR_PORTAL_COOKIE="<session-cookie>"
export MIRROR_LMS_URL="https://<lms-url>"
export MIRROR_COMPLIANCE_INGESTER_URL="https://<ingester-url>"
export MIRROR_TELEMETRY_API_URL="$MIRROR_API_URL"
python3 scripts/smoke/platform_full_surface_smoke.py

Local SDK tests are on by default. Set MIRROR_SKIP_LOCAL_SDK_TESTS=1 only when validating a remote deployment from a machine without the SDK build environment.

Ops-only runtime-lane proof is separate. Keep direct runtime URLs, host identifiers, and infrastructure-specific evidence in internal release handoff documents, not customer-facing docs.

Governance Evidence

Platform services can submit normalized evidence through:

POST /mapi/v1/governance/evidence/ingest

Supported sources are gateway, agentiq, policyengine, compliance-ingester, runtime-lane, discover, connector, sdk, and portal.

Previous

Entitlements and Access

Next

Runtime Lane Proof

On this page