> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Spark: run your own code on Protokol, from dev to live
- URL: https://blog.protokol.io/spark/
- Published: 2026-11-17T17:33:03.000Z
- Updated: 2026-11-17T17:33:03.000Z
- Description: 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.
- Author: Strahinja Djuric
- Tags: Engineering

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:

```bash
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:

```bash
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`.

```bash
ptkl sandbox spark cancel --id 3fae1c2e-... --spark-env dev

```

`spark logs` fetches logs for one environment, with options to limit the output:

```bash
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`.

```bash
# 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](https://blog.protokol.io/secrets/) 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:

```bash
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](https://blog.protokol.io/forge/), 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](https://docs.protokol.io/toolkit/sandbox/?ref=blog.protokol.io): the full command reference for Sparks and runtimes
- [Secrets](https://blog.protokol.io/secrets/): encrypted Spark environment values