The Kazibee Runtime

This page covers what happens internally when code executes through Kazibee. Not how to build a plugin — but the execution model itself. How code is validated, how tools are loaded, and how the sandbox enforces boundaries.

AI-Driven Execution

The AI writes the code. Kazibee runs it safely.

An AI model decides when to use Kazibee, generates the code, and sends it for execution — all within a single conversation.

Can you check my latest emails and summarize them in a Google Sheet?

I'll use Kazibee to read your Gmail and write to Google Sheets.

const emails = await tools.gmail.getUnread({ limit: 10 });

const rows = emails.map(e => [e.from, e.subject, e.date]);

await tools.sheets.append("Email Summary", rows);

kazibee-terminal

dev@local:~/workspace $  echo 'const emails = await tools.gmail.getUnread({ limit: 10 }); ...' | kazibee exec
  ✓ AST validation passed
  ✓ Resolved 2 tools: gmail, google-sheets
  ✓ Execution complete (1.2s)
  Result: 10 emails summarized → "Email Summary" sheet updated

The AI generates the code, but never touches your APIs directly. Every snippet goes through the Kazibee runtime, which validates the AST, resolves tools, and sandboxes execution — the same pipeline every time, whether the caller is human or AI.

Execution pipeline

What happens during `kazibee exec`

Every execution follows the same four-step pipeline. No shortcuts, no bypasses. Each step must pass before the next begins.

AST Validation

Every code snippet is parsed into an Abstract Syntax Tree and validated before execution. Import declarations, require() calls, eval(), Function constructors, and dynamic imports are all detected and blocked. If validation fails, execution never starts.

Tool Resolution

The runtime queries its database to find which tools are installed for the current working directory. Tools can be installed locally (per-project) or globally. Only tools explicitly installed are available — nothing is implicit.

In-Process Tool Loading

Each tool's entry point is loaded and its default export function is called with two arguments: scoped secrets (only the env vars the user explicitly granted) and a ContextService for state persistence. The returned object becomes the tool's callable interface.

Sandboxed Execution

The validated code is wrapped in an async function with a single parameter: tools. No other dependencies are injected. The code runs with access only to the tools object and standard JavaScript builtins.

AST Validation deep dive

The validator catches escape attempts before any code runs. Here is what happens when someone tries to break out of the sandbox:

kazibee-terminal

dev@local:~/workspace $  echo "import fs from 'fs';" | kazibee exec
  Error: AST validation failed
  Line 1:1 — Import declarations are not allowed in sandboxed code
  # Execution never started. Code was rejected at the AST gate.

What the AST validator blocks:

× import declarations

× require() calls

× eval() calls

× new Function() constructors

× Dynamic import()

× process access

× __dirname / __filename

Security

Security architecture

Three layers ensure that code cannot escape its intended boundary.

Static Analysis Gate

Code is analyzed at the AST level before any execution. This is not string matching — it is full syntax tree traversal that catches all known escape vectors.

Closed Execution Surface

The tools object is the only injected dependency. No globals, no Node.js APIs, no filesystem access unless a plugin explicitly provides it.

Scoped Secret Injection

Each tool declares what environment variables it needs in a permissions.json. During install, the user grants or denies each request. At runtime, only granted secrets are injected.

Permission model

Tools declare their needs upfront. Users decide what to grant. Nothing is silent or automatic.

How a tool declares its needs (permissions.json):

{

"env": {

"GMAIL_CLIENT_ID": ["LOCAL:GMAIL_CLIENT_ID", "GLOBAL:GMAIL_CLIENT_ID", "SYSTEM:GMAIL_CLIENT_ID"],

"GMAIL_REFRESH_TOKEN": ["LOCAL:GMAIL_REFRESH_TOKEN", "GLOBAL:GMAIL_REFRESH_TOKEN"]

}

Secret sources (checked in order):

LOCAL Project-scoped env vars set via kazibee env

ENV Process environment variables (process.env)

GLOBAL User-wide env vars set via kazibee env --global

SYSTEM Env vars from the tool's setup script during installation

kazibee-terminal

dev@local:~/workspace $  kazibee install gmail kazibee/gmail
  Permissions requested by "gmail":
  Inject "GMAIL_CLIENT_ID" from:
    1) Deny
    2) LOCAL:GMAIL_CLIENT_ID
    3) GLOBAL:GMAIL_CLIENT_ID
    4) SYSTEM:GMAIL_CLIENT_ID
  Choose [1-4]: 2
  Inject "GMAIL_REFRESH_TOKEN" from:
    1) Deny
    2) LOCAL:GMAIL_REFRESH_TOKEN
    3) GLOBAL:GMAIL_REFRESH_TOKEN
  Choose [1-3]: 1
  # Tool installed. GMAIL_REFRESH_TOKEN was denied and will not be available at runtime.

The user can deny any permission. The tool still installs, but the denied secret will not be available at runtime. Tools should handle missing secrets gracefully.

Tool context and state

Tools can persist data between executions using the ContextService. This is how plugins remember things across runs.

Key-value with TTL

set(key, ttl, value), get(key), getAll(), and delete(key) with time-to-live in seconds. Expired entries are cleaned before each execution.

Constraints

64KB max per key. Values must be JSON-serializable. Keys cannot contain % or _ characters. Dot-notation keys (e.g. auth.token) expand to nested objects in getAll().

export default function main(env, context) {

return {

getToken: async () => {

const cached = await context.get("auth.token");

if (cached) return cached;

const token = await refreshAccessToken(env.REFRESH_TOKEN);

await context.set("auth.token", 3600, token); // TTL: 1 hour

return token;

}

};

}

Directory scoping

Each project directory can have its own set of installed tools. Different projects, different tool sets. Global tools are available everywhere.

→

Tools installed without --global are scoped to the current directory only

→

Tools installed with --global are available from any working directory

→

kazibee list shows exactly what is available in the current directory

kazibee-terminal

dev@local:~/workspace $  kazibee list
  Tools for ~/projects/my-app:
    gmail — Read and manage Gmail messages
      Source: github:kazibee/gmail#a1b2c3d4 (from ~/projects/my-app)
    google-sheets — Read and write Google Sheets data
      Source: github:kazibee/google-sheets#e4f5g6h7 (from ~/projects/my-app)
    image-gen — Generate images with AI
      Source: github:kazibee/image-gen#i7j8k9l0 (from /)

Local Development

Develop tools locally with link

During development, link a local directory as a tool so changes are picked up immediately without reinstalling. Linked tools take precedence over installed tools at the same directory scope — longest-path-wins, then link beats install.

`kazibee link <name> <path>`

Links a local directory as a tool under the given name. The tool is resolved from the linked path instead of the registry, so code changes take effect on the next execution without reinstalling.

`kazibee unlink <name>`

Removes a previously created link. The tool reverts to its installed version if one exists, or becomes unavailable if it was only linked.

Developer Experience

API discovery before execution

Before writing code, AI agents and developers can inspect exactly what each tool provides.

`kazibee show`

Prints combined .d.ts type interfaces for all installed tools — method signatures, parameter types, and return types. Target a specific tool with kazibee show <tool>.

`kazibee llm`

Prints the tool's llm.txt — human and AI-readable documentation with usage patterns, examples, and best practices. Without arguments, kazibee llm prints Kazibee-level docs.

kazibee-terminal

dev@local:~/workspace $  kazibee show gmail
  interface ToolInterface {
    'gmail': {
      getUnread(options?: { limit?: number }): Promise<Email[]>
      send(to: string, subject: string, body: string): Promise<void>
      search(query: string): Promise<Email[]>
    }
  }

Extensibility

Tools can expose CLI commands

Beyond runtime APIs, tools can register CLI subcommands for setup flows, OAuth authentication, and administrative tasks.

→

Tools declare a command field in package.json pointing to a module

→

Run as kazibee <tool> <subcommand> [args]

→

Commands receive resolved env vars (SYSTEM → GLOBAL → LOCAL priority)

→

If a command returns Record<string, string>, values are auto-stored as env vars

kazibee-terminal

dev@local:~/workspace $  kazibee gmail auth
  Opening browser for OAuth consent...
  ✓ Authorization successful.
  Stored env vars for "gmail": GMAIL_ACCESS_TOKEN, GMAIL_REFRESH_TOKEN

Automated setup during installation

Tools can declare a setup script via kazibee.setup in package.json. This script runs during kazibee install to populate env vars — for example, creating OAuth credentials or generating API keys. Setup env is stored per tool identity and available as the SYSTEM source at runtime.

Ready to explore?

Now that you understand how the runtime works, see what plugins are available or head back to learn more about Kazibee.

See what's available Back to home

The AI writes the code. Kazibee runs it safely.

What happens during kazibee exec

AST Validation

Tool Resolution

In-Process Tool Loading

Sandboxed Execution

AST Validation deep dive

What the AST validator blocks:

Security architecture

Static Analysis Gate

Closed Execution Surface

Scoped Secret Injection

Permission model

Tool context and state

Key-value with TTL

Constraints

Directory scoping

Develop tools locally with link

kazibee link <name> <path>

kazibee unlink <name>

API discovery before execution

kazibee show

kazibee llm

Tools can expose CLI commands

Automated setup during installation

Ready to explore?

What happens during `kazibee exec`

`kazibee link <name> <path>`

`kazibee unlink <name>`

`kazibee show`

`kazibee llm`