The autolang-compiler package bundles the Autolang VM as a WebAssembly module, so you can embed it in any JavaScript or TypeScript project - browser or Node.js - without any native build steps.

Browser (WASM)Node.jsTypeScript ready

Installation

Install the package from npm. The WASM binary is bundled - no native compilation required.

Terminal

$npm install autolang-compiler@latest

Basic Usage

Create a compiler instance with ACompiler.create(), run a script, and read the output. That's the core loop for most use cases.

import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();

// compileAndRun will refresh automatically after run vm
// if you want to run multiple times with same vm instance,
// then you can use compile and run separately
await compiler.compileAndRun("main.atl", `
    println("Initializing orchestration script")
    println("Execution runtime verified")
`);

console.log(compiler.getOutput());
// Initializing orchestration script
// Execution runtime verified

How output works

Autolang captures all print and println calls internally. Use compiler.getOutput() after execution to retrieve the full buffer. Call compiler.clearOutput() to reset it before the next run.

Configuring at Creation

Instead of setting limits and permissions individually, you can pass an ACompilerConfig object directly to ACompiler.create(). This enables declarative sandboxing before any script runs.

import { ACompiler, ACompilerConfig } from 'autolang-compiler';

const config: ACompilerConfig = {
    limits: {
        maxOpcodeCount: 500_000,
        maxMemoryBytes: 16 * 1024 * 1024, // 16 MB
    },
    compatibility: {
        strictMode: false,
        allowLateinit: true,
        allowNonNullAssertion: true,
    },
    libraries: {
        file: {
            enabled: true,
            allowRead: true,
            allowWrite: false,
            allowedPaths: ["./sandbox/data"],
        },
        http: {
            enabled: true,
            allowedDomains: ["api.example.com"],
        },
    },
};

const compiler = await ACompiler.create(config);

await compiler.compileAndRun("main.atl", `
    println("Configured sandbox running")
`);

Compile and Run Separately

When you need to validate code before running it - or run the same compiled bytecode multiple times - split the two steps. This is especially useful for agent pipelines where you want to check for errors before actually executing.

import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();
const code = `println("Running!")`;

// Compile only - does not execute
const ok = await compiler.compile("main.atl", code);

if (compiler.hasCompilerError()) {
    console.error("Compilation failed!");
} else {
    // Run once
    await compiler.run();
    console.log(compiler.getOutput());

    // Run again without recompiling
    compiler.clearOutput();
    await compiler.run();
    console.log(compiler.getOutput());
}

// Reset everything before the next compilation
compiler.refresh();

Opcode Execution Limit

Autolang tracks how many VM instructions each run executes. You can set a hard cap to stop runaway scripts - the default is 1,000,000 opcodes. This is one of the primary safety mechanisms for AI-generated code.

import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();

// Custom limit
compiler.setLimitOpcodeCount(50_000);

// Or effectively disable it (INT32_MAX)
compiler.setLimitOpcodeCount(2_147_483_647);

await compiler.compileAndRun("main.atl", `
    var i = 0
    while (true) {
        i = i + 1
        if (i >= 10) break
    }
    println("i = " + i)
`);

console.log(compiler.getOutput()); // i = 10

Keep a limit when running untrusted code

Without a limit, an infinite loop inside a script will block the JavaScript event loop entirely. Always set a reasonable cap when running AI-generated or user-supplied scripts.

Handling Runtime Exceptions

Autolang distinguishes between compile-time errors (wrong types, undefined variables) and runtime exceptions (thrown with throw, or triggered by divide-by-zero etc.). Runtime exceptions don't crash the host - they're captured and accessible from the outside.

import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();

await compiler.compileAndRun("main.atl", `
    throw Exception("Something went wrong!")
`);

if (compiler.hasException()) {
    const err = compiler.getException();
    // AException = { message: string }
    console.error("Runtime exception:", err?.message);
    // Runtime exception: Something went wrong!
}

// You can also throw from the host side:
// compiler.throwException("Triggered from JavaScript");

Compile errors vs runtime exceptions

Compile errors - caught at compile time. Check with hasCompilerError() or use the setOnError() callback.
Runtime exceptions - thrown during execution. Check with hasException() / getException().

Need to expose your own functions to scripts? See Native Libraries.

Lifecycle & Resource Disposal

Each compiler instance manages an isolated WebAssembly memory sandbox. While unused instances are eventually collected by the runtime finalization registry, explicitly calling dispose() immediately frees WASM heap allocations.

import { ACompiler } from 'autolang-compiler';

// Manual disposal
const compiler = await ACompiler.create();
try {
    await compiler.compileAndRun("main.atl", `println("Task completed")`);
} finally {
    compiler.dispose();
}

// Or with TypeScript 5.2+ explicit resource management:
// using compiler = await ACompiler.create();

AI Reference Guide

If you are building an AI agent or assistant that needs to generate Autolang code, you can feed our pre-packaged markdown guide into the LLM system prompt. This ensures the model writes syntactically valid code and adheres to compiler constraints.

Download or copy the prompt instructions at the AI Reference page.

← PreviousHttp Next →Native Libraries (npm)