Publisher engineering guide · 01

Onboard an agent with the Vintraa SDK

SDK onboarding and visual onboarding use the same public APIs. Keep hosting your application anywhere over HTTPS; Vintraa registers its URLs and release metadata, not the workload. Choose the surface that fits your process while the trust boundary stays identical.

Start SDK guide Use visual onboarding

One controlled route · 02

From your HTTPS runtime to a reviewed release.

The SDK accelerates evidence collection. It never absorbs review or activation authority.

01
Host the agent
Serve the reviewed runtime and health endpoints over HTTPS.
02
Install a client
Choose the TypeScript CLI, Python SDK, or the same public OpenAPI contract.
03
Authenticate in sandbox
Use a human device grant locally or a scoped service token in CI.
04
Author the manifest
Describe runtime, permissions, disclosures, support, and deterministic tests.
05
Register the application
Create the first DRAFT; Vintraa returns the stable app and release IDs.
06
Verify every origin
Complete an HTTPS-file ownership challenge for each declared remote origin.
07
Run a private test
Exercise one manifest-declared synthetic action in an isolated installation.
08
Pass conformance
Validate the exact release and wait for its typed operation result.
09
Submit for review
Freeze that tested digest and hand it to a human reviewer.
10
Activate explicitly
Only after certification, a separately authorised activation makes it available.

Choose your interface · 03

Three clients. One contract.

Switch paths without changing lifecycle, evidence, or authority semantics.

TypeScript + CLI

The CLI keeps lifecycle order explicit and derives stable keys for one logical publish attempt. It stops when the release reaches human review.

ShellInstall the TypeScript SDK and vintraa CLI

npm install @zyntrialabs/vintraa-agent-sdk

ShellSandbox-to-review CLI workflow

# 1. Sign in with a short-lived developer grant.
vintraa auth login --environment sandbox

# 2. Create, inspect, and validate a manifest.
vintraa agent init --manifest ./vintraa-agent.yaml
vintraa agent validate --manifest ./vintraa-agent.yaml

# 3. Register the first DRAFT. Save the returned app and release IDs.
vintraa agent push \
  --manifest ./vintraa-agent.yaml \
  --publisher <publisher-uuid>

# 4. Reserve an HTTPS-file challenge for every declared origin.
vintraa publisher verify-domain https://agent.example.com \
  --method https_file \
  --publisher <publisher-uuid> \
  --app <app-id> \
  --proof-file ./.vintraa/ownership-proof.txt

# Publish that file at the returned URL, then ask Vintraa to verify it.
vintraa publisher verify-domain \
  --challenge <challenge-uuid> \
  --publisher <publisher-uuid> \
  --app <app-id>

# 5. Validate, privately test, run conformance, confirm, and submit once.
vintraa agent publish \
  --manifest ./vintraa-agent.yaml \
  --publisher <publisher-uuid> \
  --app <app-id> \
  --wait submission

# 6. Read publisher-safe human-review status.
vintraa agent review list --release <release-uuid>

Use the OS-backed human refresh grant locally. For CI, inject a scoped VINTRAA_SERVICE_TOKEN from the runner's secret store.
The publish command synchronises the DRAFT, validates it, creates a digest-bound private installation, runs one declared synthetic action, waits for conformance, asks for confirmation, and submits once.
It never approves, certifies, or activates the release; --wait submission stops at IN_REVIEW.
A timeout is ambiguous: rerun the same logical attempt so its key is reused. Start a new --attempt only after a definitive terminal failure and a deliberate repair.

Manifest v2 · 04

Describe the release customers will actually run.

The manifest is a bounded public declaration, not configuration storage. On first registration, omit appId; Vintraa returns the stable identity.

Identity: Choose a stable slug, clear customer-facing job, risk, and initial visibility. Omit appId on first registration; Vintraa assigns it.
Runtime: Declare the exact HTTPS invocation, manifest, and health endpoints you operate. Every resulting origin must pass ownership verification before submission.
Actions and permissions: Give every capability a stable ID, bounded purpose, explicit approval requirement, and only the read/write permissions it needs.
Roles and approval: Publisher roles remain server-owned and cannot be self-assigned in a manifest. Capability approval declares when a customer decision is required.
Customer experience: Choose platform-native, embedded, external, or API-only independently from runtime, and declare launch and allowed origins where required.
Commercial disclosure: Declare who bills the customer and the pricing model. Publisher-managed pricing needs support, pricing, purchase, and account links.
Governance and support: State data categories, purposes, storage, retention, training use, regions, deletion, support, privacy, security, terms, and response commitments.
Release: Use semantic versions, manual activation, explicit compatibility, human-readable notes, and no mutable latest aliases.
Synthetic tests: Declare deterministic, non-sensitive input that is safe to run in an isolated private installation. Never use real customer data.

YAMLIllustrative publisher manifest v2

schemaVersion: "2.0"
application:
  slug: example-roster
  name: Example Roster Agent
  category: workforce-planning
  summary: Creates constraint-aware staff rota proposals for manager review.
  job: Propose and explain a staff rota before a manager approves it.
  risk: medium
  visibility: private
listing:
  defaultLocale: en-GB
  support:
    email: [email protected]
    url: https://publisher.example/support
    securityContact: [email protected]
    statusUrl: https://publisher.example/status
    responseCommitment: Initial response within two business days.
  documentation:
    userGuideUrl: https://publisher.example/docs/roster-agent
    apiReferenceUrl: https://publisher.example/docs/roster-agent/api
    changelogUrl: https://publisher.example/docs/roster-agent/changelog
  commerce:
    customerBillingOwner: publisher
    pricingModel: external_subscription
    pricingUrl: https://publisher.example/pricing
    purchaseUrl: https://publisher.example/buy
    accountUrl: https://publisher.example/account
  governance:
    privacyUrl: https://publisher.example/privacy
    securityUrl: https://publisher.example/security
    termsUrl: https://publisher.example/terms
    data:
      categories: [workforce-schedule]
      purposes: [rota-generation]
      storage: transient
      retentionDays: 0
      trainingUse: none
      regions: [GB]
      deletionMethod: automatic
  assets:
    icon: assets/icon.png
    screenshots:
      - assets/setup.png
      - assets/result.png
release:
  version: 2.4.0
  channel: stable
  strategy: manual
  notes: Adds preference constraints and clearer manager-facing explanations.
  changeLog:
    - kind: added
      summary: Preference constraints for consecutive shifts.
  compatibility:
    vintraaApi: ">=1.0 <2.0"
    protocol: vintraa-http-v1
    sdk:
      typescript: ">=0.2"
      python: ">=0.2"
runtime:
  adapter: vintraa-http-v1
  endpoint: https://agent.publisher.example/v1/invocations
  manifestUrl: https://agent.publisher.example/.well-known/vintraa-agent.json
  healthCheckUrl: https://agent.publisher.example/health/ready
  timeoutSeconds: 60
customerExperience:
  mode: api_only
  allowedOrigins: []
capabilities:
  - id: propose-rota
    title: Propose a rota
    description: Build a constraint-aware rota proposal for manager review.
    approval: required_for_result
    permissions:
      - rota.read
      - rota.write
permissions:
  - id: rota.read
    label: Read rota constraints
    description: Read the staffing constraints needed to build a rota proposal.
    access: read
    risk: medium
    required: true
    purpose: Use staffing constraints to calculate a rota proposal.
    dataCategories: [workforce-schedule]
  - id: rota.write
    label: Write rota drafts
    description: Create a draft rota that remains subject to manager approval.
    access: write
    risk: medium
    required: true
    purpose: Save the proposed rota as a draft for manager review.
    dataCategories: [workforce-schedule]
tests:
  - id: manifest-health
    type: conformance
    description: Validate the published manifest and runtime health contract.
  - id: propose-rota-smoke
    type: smoke
    capability: propose-rota
    description: Verify that a private test can produce a reviewable rota draft.

Security boundary · 05

Secrets stay outside. Authority stays server-side.

No credentials in public surfaces

Never place access tokens or private keys in browser code, manifests, URLs, logs, screenshots, localStorage, examples, or checked-in files.

Short-lived human auth

The CLI stores refresh grants in the OS credential store; access tokens remain short lived and scope bound.

Scoped CI identity

Use VINTRAA_SERVICE_TOKEN only for headless CI, injected from its secret store and limited to the publisher, environment, and scopes required.

Synthetic evidence only

Private tests must use synthetic data. Do not put real customer, tenant, patient, or employee data into onboarding evidence.

Verify every origin

Verify each runtime, launch, embedded, and allowed origin separately. One successful proof never covers a different origin.

Stable retries

Reuse the same idempotency key after an ambiguous failure. A new key can duplicate a committed mutation.

Durable idempotency

Use the SDK's Redis-backed idempotency store in multi-process production; an in-memory store cannot coordinate workers.

Exact-body signatures

Preserve raw request bytes until signature verification completes. Enforce bounded timestamps and use hosted public keys or the issued webhook secret.

Repair before a new attempt

Do not use random attempt IDs for ordinary retries. Start a new attempt only after a definitive terminal failure and a repaired deployment.

Trust handoff · 06

Submission is a boundary, not a shortcut.

Automation prepares evidence. Human review certifies it. Activation is a later, explicit decision.

1
DRAFTPublisher
Editable manifest and release metadata.
2
Validation + private testVintraa evidence
Digest-bound validation, synthetic execution, and conformance.
3
READYPublisher
Required machine evidence exists for the exact release.
4
IN_REVIEWHuman review
Submission is frozen. The SDK and CLI stop here.
5
CertifiedVintraa review
A human-approved, active, unexpired certification matches the frozen digest.
6
ActivatedExplicit authority
A separate authorised action makes the certified release available.

The SDK stops at IN_REVIEW. It cannot approve, certify, or activate a release. After human certification, activation remains a separately authorised operation.

Recovery guide · 07

When the path pauses, preserve the evidence.

01Invalid manifest

Run `vintraa agent validate`, use the field path in the error, remove unknown keys, and check required runtime, permission, disclosure, support, privacy, and release fields.

02Unverified origin

Create a separate challenge for every declared origin, serve its one-time value as plain text at the exact HTTPS URL without redirects, and verify before expiry.

03Failed private test

Read the exact action result, keep the test synthetic, repair the hosted runtime, and create a new logical attempt only after the failure is terminal.

04Conformance failure

Read the typed run result for that release, correct the draft or runtime, and rerun. Do not infer success from latest-history order.

05Stale manifest digest

Fetch the current DRAFT and ETag, reconcile local changes, validate the new digest, and repeat private evidence before submission.

06Authentication expiry

Run `vintraa auth token-status`, sign in again for local work, or rotate the scoped CI credential. Never copy tokens into the manifest.

07Idempotency conflict

Reuse the key only for the same exact payload. If you intentionally changed the payload after a definitive result, begin a new logical attempt with a new key.

08Review pending

IN_REVIEW is the expected SDK boundary. Read publisher-safe review status and respond to findings; only Vintraa can certify, and activation remains explicit afterward.

Keep building · 08

Canonical next stops.

Use public contract surfaces for implementation and the visual route when a human prefers guided forms.

Onboard an agent with the Vintraa SDK

Host the agent

Install a client

Authenticate in sandbox

Author the manifest

Register the application

Verify every origin

Run a private test

Pass conformance

Submit for review

Activate explicitly

TypeScript + CLI

No credentials in public surfaces

Short-lived human auth

Scoped CI identity

Synthetic evidence only

Verify every origin

Stable retries

Durable idempotency

Exact-body signatures

Repair before a new attempt

Canonical next stops.