Skip to documentation
Rat Things
Browse documentation
Documentation/Publications: files, sites, and video
Raw Markdown Edit this page

Publications: files, sites, and video#

Publications give retained files, static sites, and videos expiring browser access while S3 stays private. This page covers the contract and deployment; use publish and share agent work for CLI commands and recipient checks.

The model#

  • A blob is immutable bytes plus a digest, size, and media type. Storage coordinates stay inside the S3 adapter.
  • A publication is an immutable directory with a required index.html, a manifest, provenance, and one of the tagged kinds file, site, or video. Its ready manifest lives under a reserved internal prefix that the edge router never serves.
  • A share grant is an unguessable bearer token authorizing one publication until an explicit expiry.

Session artifact publishing#

Managed environments retain regular files beneath /workspace/outputs as immutable Session Artifacts after completed Turns. Select saved artifact IDs explicitly when publishing. The owner-checked source resolver verifies the whole selection before reading content or writing a publication; artifact IDs from another owner, another Session, or deleted artifacts are rejected.

The publication ID derives from the Session, normalized specification, selected paths, content digests and media types. Its manifest is committed last. Repeating the same selection reuses the publication and mints a fresh grant. Its provenance records the Session and artifact IDs. A publication remains available independently of the live environment and its source artifact's subsequent deletion, subject to the publication retention policy and grant expiry.

Control API#

Use the IAM-authenticated control endpoint, separate from the standard Agents API:

POST /v1/sessions/{sessionId}/publications
Content-Type: application/json

{
  "publication": {"version":"1","kind":"site","entrypoint":"index.html"},
  "files": [
    {"artifact_id":"art_index","path":"index.html"},
    {"artifact_id":"art_style","path":"style.css"}
  ]
}

Each artifact ID and relative path must be unique. Paths cannot contain traversal, absolute paths or backslashes. file specifications select path; video specifications select path and an optional poster; site specifications select an optional root and entrypoint. Only the selected saved bytes are available to the builder. The agent's live filesystem does not grant publication access.

The response URL is on a publication-specific host. Its /__share/{token} route validates the encrypted S3 share record and redirects to a cryptographically signed first-page URL while also installing host-only signed cookies. The first page therefore opens even when a browser delays or drops cookies from the redirect. CloudFront repeats the cookies on that successful page response, and generated file and video viewers also carry the signed authorization into their asset requests. Relative site assets then work naturally beneath the same isolated origin for the grant lifetime.

AWS setup#

Publication delivery is opt-in because CloudFront custom-domain resources require deployment-owned DNS and key material. Configure:

enable_publication_delivery         = true
publication_base_domain             = "agent-content.example"
publication_certificate_arn         = "arn:aws:acm:us-east-1:111122223333:certificate/..."
publication_public_key_pem          = <<-PEM
  -----BEGIN PUBLIC KEY-----
  ...
  -----END PUBLIC KEY-----
PEM
publication_private_key_secret_arn  = "arn:aws:secretsmanager:us-west-2:111122223333:secret:agent/publication-key-..."
publication_route53_zone_id         = "Z0123456789EXAMPLE"

Use a separate registrable user-content domain, not a subdomain or sibling of the application's cookie domain; this prevents broad application cookies from reaching generated sites. The ACM certificate must cover the wildcard (for example *.agent-content.example) and be issued in us-east-1, as required by CloudFront. Store the matching RSA private key only in Secrets Manager. Supplying the optional Route 53 zone lets the module create wildcard A and AAAA aliases; otherwise create equivalent DNS records with the external provider.

One CloudFront distribution maps validated publication hosts to owner-scoped S3 prefixes. Origin Access Control keeps S3 private, and a trusted key group enforces the signed URLs and cookies. Distinct browser origins and cookie jars prevent one generated site from reading another publication's content.

The supplied response policy allows local inline scripts and styles needed by static agent output, but blocks cross-origin resource and API connections, framing, objects, forms, referrers, and sensitive browser capabilities.

Adding another output kind#

Add a new member to the versioned PublicationSpec tagged union and implement one PublicationBuilder. A builder receives catalog blobs and returns a directory plan or diagnostics; it does not import AWS clients, mint URLs, or write objects. Register it at composition time and add focused planning tests. The publication service owns storage and delivery.

See durable files for artifact limits, retention, and transfer behavior.