@casual-simulation/aux-vm

AUX VM

A set of abstractions and common utilities required to run an AUX on any platform.

Installation

npm install @casual-simulation/aux-vm

Usage

Create a custom simulation class

import { BaseSimulation, AuxVM } from '@casual-simulation/aux-vm';

// Simulations are wrappers for an
// AuxVM + AuxChannel combo.
// They make all the capabilities of an AUX easy to access
// and understand.
export class MySimulation extends BaseSimulation {
    constructor(
        id: string, // The ID of the
        config: { isBuilder: boolean; isPlayer: boolean }
    ) {
        super(id, config, config => new MyAuxVM(config));
    }
}

// An AUX VM is in charge of separating
// the consumer from the AUX Environment.
// Basically its a security barrier between an AUX and the consumer code.
// On Web Browsers, this is usually implemented via web workers and sandboxed iframes.
// On Node.js, this is implemented via a custom script sandbox.
// Below, you can implement your own VM.
export class MyAuxVM implements AuxVM {
    // TODO: Implement
}

Changelog

V3.8.0

Date: 10/14/2025

:rocket: Features

• Added the os.eraseInst(recordKeyOrName, instName, options?) function to delete insts programmatically.
• Added the ai.listChatModels() function to list the available chat models that the user can use based on their subscription.
• Changed webhooks to record logs to the same record that the webhook is stored in.
• Add the os.syncConfigBotTagsToURL(tags, fullHistory?) function.
  • Tells CasualOS to sync the given list of config bot tags in the URL query.
  • tags - The tags that should be synced to the URL.
  • fullHistory - Whether the a history entry should be created for every change to these tags. If false, then the URL will be updated but no additional history entries will be created. If true, then each change to the parameters will create a new history entry. Defaults to true.

:bug: Bug Fixes

• Fixed an issue where rapidly refreshing browser tabs could create duplicate remote connections that would persist in the os.remotes() list. The system now properly cleans up all remote device registrations when a connection is lost and prevents registering the current connection as a remote.
• Fixed an issue where tag masks in the shared space might be ignored after the server runs some cleanup.
• Fixed an issue where the from position values in onDrag, onDrop, onAnyBotDrag, and onAnyBotDrop events were being incorrectly rounded to integers, causing non-integer bot positions (e.g., 0.5, 0.4) to be rounded before being passed to event handlers.
• Fixed an issue where clicking the sheetPortal button in the systemPortal would only infer the dimension from gridPortal. Now it checks mapPortal first, then gridPortal, before requesting user input.
• Fixed an issue where it was not possible to publish packages to studios.
• Changed to ensure that the "Sign In" dialog is shown to unauthenticated users who are trying to access a public inst on Privo-enabled deployments.
• Static inst deletion now properly removes all associated data from browser storage. Previously, deleting a local inst would only remove it from the list while leaving bot data behind, causing old data to reappear when creating a new inst with the same name.