Verentis

Execution model

The execution lifecycle & tokens

What your engine receives at run time — the context, the scoped engine token, the identity it runs as, and how outputs are returned.

When an engine runs, Verentis hands it everything it needs and nothing it doesn't: a run context, a short-lived scoped token, and an identity to act as. Understanding these makes your engine correct and secure.

The run context

Each run receives a context describing what to do:

Target file / node

The file that triggered the run (for file-initiated runs) — its id, path and MIME type.

Workspace

The workspace the run belongs to. All access is scoped to it.

Parameters

Any inputs passed by the caller or tool invocation.

Scoped token

A short-lived access token the engine uses to call platform APIs.

Your code reads this through the language SDK rather than parsing environment plumbing directly.

The engine token

For every run, Verentis mints an engine token bounded by:

  • the permissions your manifest declared (e.g. node.file.read, node.node.create), and
  • the run's context (the workspace, and — where relevant — the file/node boundary).

The token is short-lived and audience-scoped. Use it (via the SDK) to read inputs and write outputs.

Boundaries matter

A token scoped to a node boundary confines the engine to that part of the VFS. If your engine must read inputs elsewhere (e.g. a shared library directory), it needs the appropriate broader scope — declare only what you genuinely need.

Identity: who the engine acts as

Runs act as a service principal, not a human user. For automated runs (schedules, triggers) the engine acts as a workspace service provisioned for that purpose. This keeps automated work attributable and independently governable, separate from any particular user.

A service run forwards the ambient service identity rather than minting a user/node-scoped token. This is why scheduled and triggered engine runs work without a signed-in user present.

Reading inputs & writing outputs

Inside the runtime, your code uses the language SDK:

from verentis import engine

ctx = engine.context                       # the run context (target file, params, workspace)
data = engine.files.read_json(ctx.file.path)

result = do_work(data)

# Write an output file back into the VFS
engine.files.write_json("/outputs/result.json", result)
engine.output.artifact("/outputs/result.json")

# Return structured data to the caller
engine.output.result({"rows": len(result)})

Full API

This is the real Python SDK surface — see the Python SDK reference for every method. The shape (context, scoped token, file read/write, structured result) is consistent across language SDKs and mirrors the TypeScript app SDK.

Output options

An engine can produce any combination of:

  • Structured data — stdout/JSON returned to the caller.
  • Files — written back into the workspace VFS.
  • Side-effects — calls to other platform APIs (within its granted scopes).
  • Streamed logs — for long-running modes, output streamed as it happens.

Next

Engine tools

Expose typed operations the platform and agents can invoke.

Triggers & schedules

Run automatically on cron or file changes.