Proposal: Tenki worker integration for ephemeral microVM flow runs

[BrenoLeal]

Following Prefect's contribution guidelines for new integrations, I am opening this discussion early in the process so that the maintainers and community can review the use case, proposed architecture, initial scope, and repository strategy.

I am exploring a Prefect worker integration for Tenki in collaboration with the Tenki team. The goal is to allow Prefect flow runs to execute inside isolated, ephemeral Tenki sandboxes.

As part of this initial planning and prototyping phase, I would especially appreciate guidance on whether the integration should live in the Prefect monorepo or as a separately maintained prefect-tenki package. The work is still at an early stage, and I am happy to adjust the design and contribution path based on feedback from this discussion.

Motivation

Tenki provides on-demand Linux microVM sandboxes through a Python SDK. A Prefect integration would let users execute each flow run in a fresh remote environment without operating a persistent compute cluster.

The intended user experience is:

1. Configure a work pool with worker type tenki.
2. Store Tenki credentials in a Prefect block.
3. Start a TenkiWorker alongside Prefect.
4. For each scheduled flow run, the worker creates a sandbox, runs prefect flow-run execute, reports the result, and terminates the sandbox.

Proposed components

• TenkiCredentials
• TenkiWorkerJobConfiguration
• TenkiWorkerVariables
• TenkiWorkerResult
• TenkiWorker, registered with worker type tenki

The initial configuration would expose CPU, memory, image or snapshot, outbound networking, command timeout, and a maximum sandbox duration.

Proposed lifecycle

For each flow run, the worker would:

1. Create a Tenki sandbox with an explicit maximum duration.
2. Persist the sandbox ID as the infrastructure identifier.
3. Execute the command prepared by Prefect, expected to default to prefect flow-run execute.
4. Stream remote stdout and stderr to worker logs.
5. Determine success using the complete Tenki process result, including signal or timeout information rather than only the numeric exit code.
6. Close the sandbox in a cancellation-safe finally path.
7. Implement kill_infrastructure() so Prefect cancellation and timeout cleanup can terminate a sandbox by ID.

The Tenki API credential would remain in the worker process and would not be passed into the sandbox environment. Prefect API settings required by the flow-run process would continue to be prepared through Prefect's normal job configuration lifecycle.

Initial scope

The proposed MVP would include:

• one ephemeral sandbox per flow run;
• Prefect credentials and job configuration blocks;
• execution of the standard Prefect flow-run command;
• live stdout and stderr;
• correct propagation of success, non-zero exit, timeout, and signal outcomes;
• cleanup on success, failure, exception, and cancellation;
• idempotent infrastructure termination by sandbox ID;
• mocked unit tests and a small opt-in end-to-end test;
• setup, security, image/dependency, and troubleshooting documentation.

Volumes, GPU support, inbound preview URLs, snapshot automation, and multi-sandbox workflows would be outside the first version.

Packaging and ownership

This work is being explored in collaboration with the Tenki team. If a standalone package is the preferred path, we will confirm the long-term ownership and responsibilities for maintenance, SDK compatibility, releases, documentation, security fixes, and support before publishing the first release.

I saw that the current contribution guidance generally recommends separate repositories for new integrations. I would appreciate guidance on the preferred path:

1. Would Prefect consider this integration for src/integrations in the main repository?
2. If a standalone prefect-tenki package is preferred, is there a supported way to list or link an externally maintained worker from Prefect's integration or custom-worker documentation?
3. Are prefect flow-run execute, BaseWorker.run(), and kill_infrastructure() the recommended extension points for this use case?
4. Which minimum Prefect version should a new worker target to use the current cancellation, attribution, and cleanup behavior?
5. Should remote stdout and stderr be emitted only as worker logs, or also be associated with the flow run?
6. What ownership and maintenance commitments does Prefect expect from an externally maintained worker integration?

Validation plan

Before submitting an implementation, we plan to validate:

• worker discovery and base job template generation;
• all lifecycle paths with a mocked Tenki SDK;
• cancellation during sandbox creation and command execution;
• teardown failures and repeated cleanup requests;
• secret redaction in configuration and logs;
• one real flow run using a short-lived sandbox and a publicly reachable Prefect API endpoint.

I am happy to adjust the design and repository strategy as the work progresses. Would this integration be useful to the Prefect community, and which contribution path would the maintainers prefer?

[zzstoatzz]

sounds great @BrenoLeal - i recommend creating your own prefect-tenki repo/package with the worker definition and if it sees widespread adoption we'd be happy to consider promoting it to a first class integration. let us know how we can help