Skip to main content

Public System Design

This page explains how Shroud works at a system level without exposing proprietary implementation details.

Shroud is built as identity infrastructure for AI agents. The product model is simple:

  • the customer orchestrator requests a temporary profile
  • Shroud provisions the identity resources for that profile
  • the agent uses those resources to complete a task
  • Shroud captures verification events and enforces policy
  • the profile is destroyed when the task is done

The important boundary is that the agent uses identity resources, but Shroud owns the lifecycle of those resources.

Public Architecture

This page describes the public operating model of Shroud. It intentionally omits internal scoring systems, abuse controls, provider selection logic, and other implementation-sensitive details.

Why Shroud Exists​

Agents increasingly need to:

  • sign up for services
  • receive verification emails
  • handle SMS OTP flows
  • make low-risk, policy-bounded purchases

Most teams do not want an agent using:

  • a real employee inbox
  • a real personal phone number
  • a primary company card

Shroud provides a safer alternative by issuing a temporary SessionProfile with tightly scoped identity resources.

Core Objects​

SessionProfile​

The SessionProfile is the main object in Shroud.

A profile is a temporary operational identity for one job, session, or workflow run. Depending on the use case, it can include:

  • a temporary inbox
  • a temporary phone number
  • a constrained virtual card
  • a generated name and billing identity bundle
  • expiration and teardown policy

Verification Events​

Shroud receives inbound email and SMS messages for active profiles, then normalizes them into structured events such as:

  • OTP codes
  • magic links
  • verification URLs
  • payment-related notifications

This means customer systems do not need to parse raw HTML emails or unstructured SMS content themselves.

Payment Policy​

If a profile includes a card, Shroud applies policy controls such as:

  • max spend
  • currency limits
  • single-use behavior
  • task-scoped expiration
  • approval requirements

Main System Actors​

Developer or Product Team​

This is the customer integrating Shroud into a product, internal workflow, or automation stack.

Customer Orchestrator​

This is the customer-controlled runtime that starts jobs, requests profiles, launches agents, and receives events from Shroud.

Agent​

This is the execution layer that browses, signs up, verifies, or performs an approved internet task using the profile it receives.

Shroud Control Plane​

This is the backend service that provisions resources, tracks lifecycle state, and enforces policy.

External Providers​

These are the downstream systems that supply the underlying resources:

  • inbox routing
  • phone numbers
  • payment instruments

High-Level Flow​

The public Shroud flow looks like this:

  1. A customer system creates a task.
  2. The customer orchestrator requests a SessionProfile.
  3. Shroud provisions the requested identity resources.
  4. The orchestrator launches an agent with scoped profile data.
  5. The agent interacts with the external service.
  6. Verification messages flow back into Shroud.
  7. Shroud extracts structured signals and sends them back to the orchestrator.
  8. The agent continues and completes the task.
  9. The customer destroys the profile.
  10. Shroud revokes or tears down the resources and records the session outcome.

The safest model is orchestrator-mediated usage.

That means:

  • the orchestrator requests the profile
  • the agent receives only the fields needed for the task
  • verification events return to the orchestrator
  • teardown is triggered by backend policy or explicit customer action

This is preferable to letting a free-running agent choose providers, allocate phone numbers, or manage cards directly.

Public Component Model​

From the outside, Shroud can be understood as five major parts.

1. API Layer​

The API is the main integration surface for:

  • profile creation
  • profile lookup
  • event access
  • destruction
  • policy and webhook management

2. Provisioning Layer​

This layer allocates and attaches resources to a profile.

Examples:

  • creating an inbox route
  • assigning a phone number
  • issuing a task-bounded card

3. Verification Layer​

This layer receives inbound email and SMS data, validates it, and converts it into structured events that customer systems can consume.

4. Policy Layer​

This layer governs:

  • spend limits
  • profile lifetime
  • resource scope
  • approval behavior
  • teardown rules

5. Audit Layer​

This layer records profile history so customers can understand:

  • what was provisioned
  • what events were received
  • what actions occurred
  • when teardown completed

Lifecycle Model​

Profiles should be treated as explicit stateful objects, not vague agent memory.

A typical lifecycle is:

  • requested
  • provisioning
  • ready
  • in_use
  • waiting_for_verification
  • completed
  • destroying
  • destroyed

This makes the system easier to operate, audit, retry, and reason about.

Example Use Case​

Consider a company that wants an internal agent to start a low-cost SaaS trial for research purposes.

The service requires:

  • signup
  • email verification
  • SMS verification
  • a credit card for a capped trial

The company flow would look like this:

  1. A human approves the task and budget.
  2. The customer orchestrator requests a profile from Shroud.
  3. Shroud returns a generated identity, email, phone number, and capped card.
  4. A browser agent signs up with those details.
  5. The target service sends an email verification link and SMS OTP.
  6. Shroud receives both, extracts the useful information, and sends structured events back to the orchestrator.
  7. The orchestrator resumes the workflow.
  8. The agent completes signup and uses the constrained card only within policy.
  9. The customer destroys the profile.
  10. Shroud tears down the resources and preserves the audit trail.

This is the value of the platform: agents can complete real tasks with tighter controls and less exposure to real credentials.

Design Principles​

The public Shroud architecture is guided by a few core principles:

  • profiles are the unit of isolation
  • the backend owns provisioning and teardown
  • structured events are better than raw payload forwarding
  • policy is a core product surface
  • auditability is part of the platform, not an add-on