Spark: run your own code on Protokol, from dev to live
A Spark is a short-lived, versioned function you deploy to dev, call by name, and release to live, with its own environment variables per environment.
Sometimes a component function or a workflow isn't the right home for your code. You want a small piece of logic that runs on its own, answers a request, and can be versioned and promoted like everything else. That is what a Spark is. This post covers what a Spark is, how you deploy and promote one, how its two environments work, and how its environment variables are written.
What a Spark is
Sandbox is the platform's compute layer for user-deployed code. It has two execution models:
| Model | What it is |
|---|---|
| Spark | Short-lived, FaaS-style functions or apps. Deployed by version, promoted from dev to live, and invoked by name. |
| Runtime | Long-running deployments, such as a user-defined API. |
This post is about Sparks. Runtimes share the same command group and are summarised near the end.
You work with Sandbox from the ptkl sandbox command line or the SDK: the CLI maps one to one onto the SDK Sandbox client, which lives in @ptkl/sdk/beta.
Versions and environments
Two ideas organise a Spark's life: versions and environments.
- Every Spark is identified by a uuid and has numbered versions. You deploy a specific version.
- Every Spark has two environments,
devandlive. You deploy a version todev, try it, and when you are happy you release that version tolive, the live/public environment.
This is the same Dev and Live split that components, workflows, functions and Forge apps follow across the platform: develop and test in Dev before changes reach production.
Deploying and promoting a Spark
The ptkl sandbox spark commands cover the whole cycle.
| Command | What it does |
|---|---|
spark list |
List all Sparks for the current project |
spark deploy |
Deploy a specific version to the dev environment |
spark release |
Release a deployed version to the live/public environment |
spark cancel |
Cancel an in-progress deployment |
spark exec |
Execute a deployed Spark by name |
spark logs |
Fetch logs for a Spark |
Deploy and release take the Spark's uuid and the version:
ptkl sandbox spark deploy --id 3fae1c2e-... --version 3
ptkl sandbox spark release --id 3fae1c2e-... --version 3
Running a Spark
spark exec invokes a deployed Spark by name and sends it an HTTP-style request:
ptkl sandbox spark exec --name send-welcome-email --data '{"userId":"u_123"}'
| Option | Meaning |
|---|---|
-n, --name |
Spark name (required) |
-d, --data |
Request body as a JSON string |
-m, --method |
GET, POST, PATCH, PUT or DELETE (default POST) |
-q, --query |
Query parameters as a JSON object string |
-H, --headers |
Request headers as a JSON object string |
Cancelling and reading logs
If a deployment is in progress and you want it stopped, spark cancel does that. It takes the Spark uuid and an optional --spark-env of dev or live. If you leave it out, the server uses dev.
ptkl sandbox spark cancel --id 3fae1c2e-... --spark-env dev
spark logs fetches logs for one environment, with options to limit the output:
ptkl sandbox spark logs --id 3fae1c2e-... --spark-env live --limit 100
You can also pass --level to filter by log level and --since to fetch only logs after a timestamp.
The typical flow
- Deploy a version to
dev. - Call it with
spark execand check the result and the logs. - Release the same version to
live.
# 1. Deploy a spark version to dev
ptkl sandbox spark deploy --id 3fae1c2e-... --version 3
# 2. Try it
ptkl sandbox spark exec --name send-welcome-email --data '{"userId":"u_123"}'
# 3. Promote to live
ptkl sandbox spark release --id 3fae1c2e-... --version 3
You release a version that is already deployed, so promotion is a deliberate step you take after testing.
Spark environment variables
A Spark has its own environment variables, separately for dev and live.
A variable that holds a key, token or password can be stored as a secret. Secrets are encrypted, write-only and never shown again; our secrets post covers them in full.
Changing a Spark's environment needs the manage::spark sandbox permission.
Besides its own variables, a deploy hands the Spark the project's global environment that the deploying user is allowed to read.
Runtimes, briefly
A runtime is for something that stays up, such as an API, rather than something that answers a request and finishes. The commands mirror the Spark ones:
ptkl sandbox runtime deploy --ref api-gateway
ptkl sandbox runtime restart --ref api-gateway
ptkl sandbox runtime logs --ref api-gateway --lines 200
runtime list lists a project's runtimes. --ref takes the runtime's name or uuid.
When to use a Spark
Use a Spark when you want your own code to run as a named, versioned unit that you promote deliberately from dev to live: a small function such as send-welcome-email, invoked by name with a request body. Use a runtime when you need a long-running service. If you are building a full app with its own UI inside the platform, that is a Forge app, a different execution model, with its own ptkl forge commands.
A worked example
Say you have a Spark called send-welcome-email, and you have just finished version 3.
ptkl sandbox spark deploy --id <uuid> --version 3puts version 3 indev.ptkl sandbox spark exec --name send-welcome-email --data '{"userId":"u_123"}'calls it with a test user.- If something looks wrong,
ptkl sandbox spark logs --id <uuid> --spark-env devshows what it logged. - When it behaves,
ptkl sandbox spark release --id <uuid> --version 3makes version 3 the live one. - After release,
ptkl sandbox spark logs --id <uuid> --spark-env live --limit 100lets you watch it in production.
Learn more
- ptkl sandbox: the full command reference for Sparks and runtimes
- Secrets: encrypted Spark environment values