ptkl sandbox
Manage Sandbox sparks and runtimes from the command line.
Overview
Sandbox is the platform's compute layer for user-deployed code, with two execution models:
- Spark — short-lived FaaS-style functions/apps, deployed by version, promoted from
devtolive, and invoked by name (spark exec). - Runtime — long-running deployments (user-defined APIs).
ptkl sandbox maps 1:1 onto the SDK Sandbox client (@ptkl/sdk/beta).
Subcommands
| Subcommand | Description |
|---|---|
spark list |
List all sparks for the current project |
spark deploy |
Deploy a specific spark version to the dev environment |
spark release |
Release a deployed spark version to the live/public environment |
spark cancel |
Cancel an in-progress spark deployment |
spark exec |
Execute a deployed spark by name |
spark logs |
Fetch logs for a spark |
runtime list |
List all runtimes for the current project |
runtime deploy |
(Re)deploy a runtime |
runtime restart |
Restart a running runtime |
runtime logs |
Fetch logs for a runtime |
tier |
Get the current project's spark tier (plan/quota) |
Spark
ptkl sandbox spark list
List all sparks for the current project.
ptkl sandbox spark deploy
Deploy a specific spark version to the dev environment.
| Option | Description |
|---|---|
-i, --id <uuid> |
Spark uuid (required) |
-v, --version <version> |
Version to deploy (required) |
ptkl sandbox spark release
Release a deployed spark version to the live/public environment.
| Option | Description |
|---|---|
-i, --id <uuid> |
Spark uuid (required) |
-v, --version <version> |
Version to release (required) |
ptkl sandbox spark cancel
Cancel an in-progress spark deployment.
| Option | Description |
|---|---|
-i, --id <uuid> |
Spark uuid (required) |
--spark-env <env> |
Spark environment: dev | live (defaults to dev on the server) |
ptkl sandbox spark exec
Execute a deployed spark by name.
| Option | Description |
|---|---|
-n, --name <name> |
Spark name (required) |
-d, --data <json> |
Request body as a JSON string |
-m, --method <method> |
HTTP method: GET | POST | PATCH | PUT | DELETE (default: POST) |
-q, --query <json> |
Query params as a JSON object string |
-H, --headers <json> |
Request headers as a JSON object string |
ptkl sandbox spark logs
Fetch logs for a spark.
ptkl sandbox spark logs -i <uuid> [--spark-env <env>] [-l <limit>] [--level <level>] [--since <since>]
| Option | Description |
|---|---|
-i, --id <uuid> |
Spark uuid (required) |
--spark-env <env> |
Spark environment: dev | live |
-l, --limit <limit> |
Number of log lines to fetch |
--level <level> |
Filter by log level |
--since <since> |
Only fetch logs since this timestamp |
Runtime
ptkl sandbox runtime list
List all runtimes for the current project.
ptkl sandbox runtime deploy
(Re)deploy a runtime.
| Option | Description |
|---|---|
-r, --ref <ref> |
Runtime name/uuid (required) |
ptkl sandbox runtime restart
Restart a running runtime.
ptkl sandbox runtime logs
Fetch logs for a runtime.
ptkl sandbox tier
Get the current project's spark tier (plan/quota).
Typical Workflow
# 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
# 4. For a runtime: deploy and restart
ptkl sandbox runtime deploy --ref api-gateway
ptkl sandbox runtime restart --ref api-gateway
See Also
ptkl forge— build, bundle, and deploy Forge apps (a different execution model)- Toolkit Overview — all available toolkit commands