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, dev and live. You deploy a version to dev, try it, and when you are happy you release that version to live, 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

  1. Deploy a version to dev.
  2. Call it with spark exec and check the result and the logs.
  3. 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.

  1. ptkl sandbox spark deploy --id <uuid> --version 3 puts version 3 in dev.
  2. ptkl sandbox spark exec --name send-welcome-email --data '{"userId":"u_123"}' calls it with a test user.
  3. If something looks wrong, ptkl sandbox spark logs --id <uuid> --spark-env dev shows what it logged.
  4. When it behaves, ptkl sandbox spark release --id <uuid> --version 3 makes version 3 the live one.
  5. After release, ptkl sandbox spark logs --id <uuid> --spark-env live --limit 100 lets you watch it in production.

Learn more

  • ptkl sandbox: the full command reference for Sparks and runtimes
  • Secrets: encrypted Spark environment values