Engine manifest reference · Verentis Developer

This is the complete reference for an execution engine manifest. For the shared envelope (api-version, kind, metadata), see Manifests: the contract.

A complete example

api-version: verentis.io/v1
kind: ExecutionEngine

metadata:
  name: python
  display-name: Python
  description: Runs Python scripts in a sandboxed container
  icon: file-code
  version: 1.0.0
  author: Verentis
  labels:
    language: python

spec:
  runtimes:
    docker:
      image: ghcr.io/verentis/python-engine:1.0.0
      pull-policy: IfNotPresent
    wasm:
      module: /applications/python/pyodide.wasm
      runtime: pyodide
      adapter: /applications/python/pyodide-runner.js
      server-compatible: false
      client-compatible: true

  file-types:
    - pattern: text/x-python
      extensions: [".py"]
      priority: 100

  execution-modes:
    - request-response
    - long-running
    - scheduled
    - event-driven

  tools:
    - name: run-script
      description: Execute a Python script and capture stdout
      input-schema:
        type: object
        properties:
          args: { type: array, items: { type: string } }
      output-schema:
        type: object
        properties:
          stdout: { type: string }
          exitCode: { type: integer }

  capabilities:
    - file:read
    - file:write

  permissions:
    - node.file.read
    - node.node.create

  resources:
    cpu: "500m"
    memory: "512Mi"
    timeout: 120
    max-concurrent: 4
    storage: "1Gi"

  sandbox:
    network: none
    allowed-hosts: []
    read-only-root: true
    no-new-privileges: true

  priority: 10

`spec`

runtimesobject

How the engine executes — docker and/or wasm. See Runtimes.

file-typesobject[]

Extension→MIME rules that make files runnable by this engine. See file-types.

execution-modesstring[]

Which modes the engine supports: request-response, long-running, scheduled, event-driven.

toolsobject[]

Named operations the engine exposes, each with typed input/output schemas (MCP-style). See tools.

capabilitiesstring[]

High-level intent flags (e.g. file:read, file:write). Back them with matching permissions.

permissionsstring[]

The platform scopes the engine requires; these bound the run's scoped token.

resourcesobject

CPU/memory/timeout/concurrency limits. See resources.

sandboxobject

Network and filesystem isolation policy. See sandbox.

settingsobject[]

Workspace settings and secrets provisioned into runs. See settings.

priorityint

Default resolution priority for the engine; per-file-type priorities take precedence.

`runtimes`

runtimes:
  docker:
    image: ghcr.io/you/engine:1.0.0
    pull-policy: IfNotPresent
  wasm:
    module: /applications/you/module.wasm
    runtime: wasmtime
    adapter: /applications/you/runner.js
    server-compatible: true
    client-compatible: true

docker

imagestring

The container image to run.

pull-policystring

When to pull the image (e.g. IfNotPresent, Always).

wasm

modulestring

The WASM module location (a VFS path or URL).

runtimestring

The WASM runtime (e.g. wasmtime, pyodide).

adapterstring

The engine-owned worker that implements the client warm/run protocol — a VFS path or origin URL. The platform loads it generically, so your browser engine ships its own worker here (the symmetry with docker.image).

server-compatiblebool

Compatibility metadata retained in the manifest model. The current execution selector has no server-side WASM target; server execution always uses Docker.

client-compatiblebool

Whether the WASM module can run client-side (in the browser).

`file-types`

file-types:
  - pattern: text/x-python
    extensions: [".py"]
    priority: 100

patternstring

The MIME type assigned to matching files.

extensionsstring[]

The extensions this rule matches, each with a leading dot.

priorityint

Higher wins when several rules match the same extension.

`tools`

Each tool is a named, typed operation the platform (and AI agents) can discover and invoke:

namestring

Tool identifier.

descriptionstring

What the tool does.

input-schemaobject

JSON Schema for the tool's input.

output-schemaobject

JSON Schema for the tool's output.

See Engine tools for the MCP-style interface.

`resources`

cpustring

CPU request/limit (e.g. 500m).

memorystring

Memory request/limit (e.g. 512Mi).

timeoutint

Maximum run duration in seconds. Programs default to 300 seconds unless their ScriptRunresources.timeout requests a longer duration; that request cannot exceed this engine ceiling.

max-concurrentint

Maximum concurrent runs of this engine.

storagestring

Scratch storage size (e.g. 1Gi).

`sandbox`

networkstring

Network policy (e.g. none for no egress).

allowed-hostsstring[]

Hosts the engine may reach when network egress is permitted.

read-only-rootbool

Mount the root filesystem read-only.

no-new-privilegesbool

Prevent privilege escalation in the container.

`settings`

Workspace settings and secrets your engine requires. Declared entries are auto-registered as workspace setting definitions — namespaced {metadata.name}.{key} — so admins can supply values in the workspace settings UI (and are prompted during marketplace install). At run time the platform provisions the configured values into the run: env-mapped entries become real container environment variables, and the full map lands in context.json under settings (read it with engine.settings.get("api-key") in the Python SDK).

spec:
  settings:
    - key: api-key                # stored as {metadata.name}.api-key
      env: MY_SERVICE_API_KEY     # exposed as an environment variable
      secret: true
      required: true
      display-name: Service API key
      description: Used to call the upstream service.
    - key: region
      type: select
      options: [eu, us]
      default: eu

keystring

Required

Short key, stored namespaced as {metadata.name}.{key} in the workspace settings store.

envstring

Environment variable name provisioned into runs (UPPER_SNAKE_CASE; the VERENTIS_ prefix is reserved).

secretbool

Secret values are server-only: they are provisioned into Docker runs and never delivered to browser (WASM) contexts — an engine declaring a secret always executes server-side. Defaults to false.

requiredbool

Required settings prompt during install, and an execution fails fast with a clear message when no value is configured. Defaults to false.

display-namestring

Label shown in the workspace settings UI.

typestring

Value data type: string (default), number, boolean or select.

defaultany

Default value used when the workspace hasn't configured one. Not allowed for secrets.

optionsstring[]

Allowed values when type is select.

Secrets force the Docker runtime

A wasm-only engine cannot declare secrets — there is no server runtime to provision them into, and secrets never reach the browser. verentis validate reports this as an error.

First-party signature

First-party engines may carry a signature block verified against a configured Verentis public key. It is an unforgeable trust signal that gates optimisations like warm pooling. Third-party engines run fully sandboxed without it — you don't need a signature to publish.

Runtimes

Choose Docker, server-WASM, or browser-WASM.

The execution model

Context, tokens and identity during a run.