Scripting
Write Kotlin scripts that run inside the platform — triggered by pipelines, exposed as API endpoints, or used as AI agent tools. Scripts execute on a JVM with guardrails against common dangerous operations, but are not fully sandboxed.
Overview
Bosca includes an embedded Kotlin Script (KTS) engine. Scripts are .bosca.kts files evaluated by Kotlin's embedded compiler. They can resolve Bosca services and return values from a main { } block. Author scripts as trusted platform code: service calls do not automatically repeat API-controller authorization.
Script Types
| Type | Purpose | Execution |
|---|---|---|
GENERAL | Utility scripts | Manual via GraphQL |
TRIGGER | React to platform events | Async via job queue |
TOOL | AI agent tools | Called by AI agents |
API | HTTP endpoints | GET/POST /api/v1/s/{key} |
EPHEMERAL | Temporary/one-shot scripts | Soft-deleted on deletion, then purged by the retention job |
Writing Scripts
Scripts extend BoscaScript implicitly. They have access to a context object, the authentication context, a coroutine scope, and a log logger. Read typed input with context.get(serializer, key). Use the main {} block for async work:
Submit { "name": "Alex" } as input; the result is { "message": "Hello, Alex" }. The final value of main { } becomes the script result.
provide<T>() — the same DI mechanism used by the rest of the platform. The full server classpath is available at compile time. Running Scripts from Events
To run a script when a platform event fires, create a Pipeline whose accepted input type is the event, add an Execute Script node, and mark the pipeline Active. When the event fires, the pipeline is enqueued as a background job and executed asynchronously — and the same graph can filter, transform, and combine the event data before the script runs.
Event-triggered pipelines execute under the configured pipelines service account. The Execute Script node receives the pipeline run's authentication and passes the node's inbound value as script input. Manual and API pipeline runs retain the caller's identity. An event payload is ordinary input here; read its fields with context.get().
Available events
Choose an event type from the installed pipeline type catalog. Generated event dispatch uses the Kotlin class's fully qualified name, such as bosca.content.collection.events.CollectionCreated. Active matching pipelines are dispatched through durable background jobs.
API Scripts
Scripts with type API are exposed as HTTP endpoints at /api/v1/s/{key}:
- POST — request body is parsed as JSON; read fields through
context.get() - GET — query parameters are converted to a JSON object
- Public scripts — no authentication required
- Non-public scripts — caller must have
EXECUTEpermission - Timeout — 30 seconds
AI Agent Tools
Scripts with type TOOL can be exposed as AI agent tools through the agent tool integration. Supply an inputSchema describing the accepted JSON object and return the value from main { }. Set the schema on the script record; a Kotlin comment does not configure it. For example:
Security Guardrails
Scripts have some protections against accidental misuse, but they are not a full sandbox. A script running without authentication can still call services and modify data. These guardrails reduce the surface area for common mistakes:
Source validation
Applied before saving and before compilation. Blocks:
- Import aliasing of
System(e.g.,import java.lang.System as Sys) - Method references to
System - Any
System.xxxcall except:currentTimeMillis,nanoTime,lineSeparator,identityHashCode,arraycopy - Any reference to
Runtime
Restricted class loader
The default class-loader allowlist includes:
bosca.*,kotlin.*,kotlinx.*,java.lang.*,java.util.*,java.time.*,java.math.*,java.text.*,org.slf4j.Logger
Hard-denied even within allowed prefixes: ProcessBuilder, reflect.*, ClassLoader, java.io.*, java.nio.*, java.net.*, Runtime, Thread
Execution timeout
The local engine defaults to 600 seconds (configurable). GraphQL and remote execution impose a five-minute limit; API routes impose a 30-second limit.
Permissions
Scripts have group-based ACL via ScriptPermission (VIEW/EXECUTE/MANAGE). Script management operations use the admin group or the operation-specific permission checks.
Compilation & Caching
Scripts are compiled to JVM bytecode and cached in two tiers:
- In-memory — Caffeine cache (up to 500 entries, one hour after last access)
- Persistent — compiled bytecode stored in the platform database with a compiler fingerprint (SHA-256 of the compiler version, Kotlin version, and JVM target)
Compilation runs on a single-thread dispatcher with a mutex to prevent redundant parallel compilations of the same script.
The local Compose stack uses a JVM runner for script execution. Saving a script and executing it are separate operations; the API routes also require type API and an enabled script. See scripting/scripting/src/main/resources/graphql/scripts.graphqls for the complete record input and mutations.