Initialize workflow worker package (deprecated - use @vertesia/create-plugin instead)
npm install @vertesia/create-workerThis package scaffolds a Vertesia custom Temporal worker project.
Custom workers allow you to deploy your own Temporal workflows and activities to the Vertesia cloud platform.
Visit https://vertesiahq.com for more information about Vertesia.
1. Docker (with buildx support) installed locally.
2. Vertesia CLI application. The CLI will be automatically installed when initializing the worker project if you didn't install it previously.
Run the following command:
``bash`
npm init @vertesia/worker
Follow the instructions on screen. You need to define an organization and a name for your worker. The organization must be unique inside Vertesia and is usually the name of your Vertesia organization account. The worker name identifies the project within your organization.
The generated project is a TypeScript project using Temporal as the workflow system.
The generated project includes:
``
├── src/
│ ├── activities.ts # Activity implementations (API calls, I/O operations)
│ ├── workflows.ts # Workflow definitions (orchestration logic)
│ ├── main.ts # Worker entry point
│ ├── debug-replayer.ts # Debugging tool for workflow replay
│ ├── activities.test.ts # Unit tests for activities
│ └── test/
│ └── utils.ts # Test utilities
├── bin/
│ └── bundle-workflows.mjs # Workflow bundler script
├── vitest.config.ts # Test configuration
├── tsconfig.json # TypeScript configuration
├── tsconfig.test.json # TypeScript configuration for tests
├── Dockerfile # Container build configuration
└── package.json # Project configuration
`bash`
pnpm install
pnpm run build
The build process:
1. Compiles TypeScript to JavaScript
2. Bundles workflows into a single file (required by Temporal)
The project uses Vitest with Temporal's MockActivityEnvironment for testing activities.
`bash`
pnpm test
Tests are located in *.test.ts files alongside the source code.
Activities (src/activities.ts):
- Activities are functions that perform I/O operations (API calls, file access, etc.)
- They run outside the Temporal workflow sandbox
- Use getVertesiaClient(payload) to get an authenticated Vertesia client
- Activities can be retried automatically on failure
Workflows (src/workflows.ts):
- Workflows orchestrate activities and define the business logic
- They must be deterministic (no direct I/O, random, or time operations)
- Use proxyActivities to call activities from workflowsWorkflowExecutionPayload
- Workflows receive with objectIds and vars
Export your workflows and activities from these files to make them available to the worker.
Running with a local Temporal server is useful for integration testing before deployment.
Install the Temporal CLI, then start the dev server:
`bash`
temporal server start-dev
In another terminal:
`bash`
pnpm run start
Using the Temporal CLI:
`bash`
temporal workflow start --name exampleWorkflow -t agents/your-org/your-worker --input-file INPUT.json
Where INPUT.json contains the workflow parameters:
`json`
{
"objectIds": ["content-object-id"],
"event": "workflow_execution_request",
"auth_token": "your-auth-token",
"account_id": "your-account-id",
"project_id": "your-project-id",
"config": {
"store_url": "https://zeno-server.api.vertesia.io",
"studio_url": "https://studio-server.api.vertesia.io"
},
"vars": {
"dryRun": true
}
}
You can debug workflows by replaying them locally using the Temporal replayer in src/debug-replayer.ts.
See https://docs.temporal.io/develop/typescript/debugging for more information.
Worker configuration is defined in package.json under the vertesia section:
`json`
{
"vertesia": {
"pm": "pnpm",
"image": {
"repository": "us-docker.pkg.dev/dengenlabs/us.gcr.io",
"organization": "your-org",
"name": "your-worker"
}
}
}
The worker domain (task queue) is automatically constructed as: agents/{organization}/{name}
`bash`
vertesia worker build
This builds a Docker image tagged as your-organization/your-worker:latest.
This image is only for local testing.
`bash`
vertesia worker release
The version must be in major.minor.patch[-modifier] format (e.g., 1.0.0, 1.0.0-rc1).
This creates a new Docker tag your-organization/your-worker:version from the latest image.
`bash`
vertesia worker publish
This pushes the image to Vertesia and deploys the worker.
Options:
- --push-only: Only push the image without deploying--deploy-only
- : Deploy a previously uploaded version
`bash`
vertesia worker versions
Once deployed, workflows can be triggered via:
SDK:
`javascript`
const run = await client.workflows.execute("exampleWorkflow", {
task_queue: "agents/your-org/your-worker",
objectIds: ["content-object-id"],
vars: {
dryRun: false,
},
});
CLI:
`bash`
vertesia workflows execute exampleWorkflow -o
API:
`bash``
curl --location 'https://api.vertesia.io/api/v1/workflows/execute/exampleWorkflow' \
--header 'Authorization: Bearer
--header 'Content-Type: application/json' \
--data '{
"vars": { "dryRun": false },
"task_queue": "agents/your-org/your-worker",
"objectIds": ["content-object-id"]
}'
Built with:
- Temporal: Workflow orchestration
- Vertesia SDK: Platform integration
- TypeScript: Type-safe development
- Vitest: Testing framework