BoscaDeveloper Documentation

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

TypePurposeExecution
GENERALUtility scriptsManual via GraphQL
TRIGGERReact to platform eventsAsync via job queue
TOOLAI agent toolsCalled by AI agents
APIHTTP endpointsGET/POST /api/v1/s/{key}
EPHEMERALTemporary/one-shot scriptsSoft-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:

Example: read input and return JSON

Submit { "name": "Alex" } as input; the result is { "message": "Hello, Alex" }. The final value of main { } becomes the script result.

Scripts resolve services using 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 EXECUTE permission
  • 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:

Example input schema

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.xxx call 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:

  1. In-memory — Caffeine cache (up to 500 entries, one hour after last access)
  2. 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.

For GraalVM native image builds (which can't embed the Kotlin compiler), a remote engine enqueues compilation/execution jobs to a JVM worker via the job queue and reads results back via PubSub + object storage.

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.

GraphQL API

graphql