Getting started

Oglama is a desktop application built on top of Chromium that allows you to automate web actions.

Create an account and download the latest version to get started. Alternatively, clone oglama/oglama and run npm start to use the latest pre-release version.

1. Agents

Agents are autonomous browser windows, each operating in its own isolated session. For security reasons, agents do not have direct access to the file system or to each other's data. You must manually specify input files as needed.

2. Modules

Agents execute small JavaScript programs called modules. Each module defines inputs, outputs, functions, and a finite-state machine. For security reasons, modules do not have direct access to the browser window. Instead, the dollar sign object ($) is used to interact with the web page, pause execution, chat with a locally running large language model, fetch user input, save results, and more.

2.1. Finite-state machine

Complex browser interactions are best modeled as a finite-state machine.

• When a user starts an agent, the state machine begins execution from the entry state.

• It then jumps from state to state with return { next: "state-key" }

• The state machine stops if an error occurs or if no next state is specified.

2.2. Functions

Functions are used to avoid code duplication within state machine states. Unlike states, a function's return value has no special significance. Functions can be called from either a state or another function using $.fn("function-key")

2.3. Inputs and outputs

Each module can define up to nine inputs and nine outputs. This limit is intended to reduce cognitive load.

Supported input and output types are: integer, string, boolean,table and files

• Inputs for each run are specified in the Settings tab. Fetch inputs in states and functions with $.ioInput*()

• Outputs are collected in the Results tab. Store outputs in states and functions with $.ioOutput*()

3. Collaboration

You can publish your modules to the module repository, allowing others to install and use your work. You can also import and export your automations as .oglama.yaml files, giving you complete privacy and control over your work.

Example

Here is an example of a small Oglama module (search.oglama.yaml) that performs a Google search.

Please note that the module is exported as a YAML file, but each function and finite-state machine state is written in pure JavaScript and relies on the dollar sign object ($) for operations.

srcStateMachine:
  - key: start
    code: |
      await $.fn("visit-google");
      await $.fn("search");
srcFunctions:
  - key: visit-google
    code: |
      // Navigate to Google and wait for page to load
      await $.navLoad("https://google.com/");
  - key: search
    code: |
      // Find the input field
      const inputKey = await $.doQuery("[name='q']");
      if ("string" !== typeof inputKey) {
        throw new Error("Could not find input field");
      }

      // Get search term from user settings
      const searchTerm = $.ioInputString("search-term");

      // Replace previous string and send enter key
      await $.doType(inputKey, searchTerm, true, true);
srcInputs:
  - key: search-term
    type: string
    name: Search term
    desc: A search term for Google
    max: 1024
    options: []
    default: oglama
srcOutputs: []

All available dollar sign object ($) methods and properties are described below.

$.args

{array}

- When used inside a state:
 array passed by previous state as { next: 'state-key', args }

- When used inside a function:
 array passed as the second argument to $.fn( 'function-key', args )

Although you can use $.global*() methods to store and retrieve data from a global store, it is sometimes better to simply pass arguments from one state to another.

srcStateMachine:
  - key: start
    code: |
      // Generate a random number
      const randomNumber = await $.fn("random", [2, 10]);

      // Pass it to the next state
      return { next: "surprise", args: [randomNumber] };
  - key: surprise
    code: |
      // Passed with { next: "surprise", args: [randomNumber] };
      const randomNumber = $.args[0];
      $.log(`The number I was thinking of was ${randomNumber}`);

      // Put the LLM to work
      const prompt = `Multiply ${randomNumber} by itself.`;
      const response = await $.llm(prompt);
srcFunctions:
  - key: random
    code: |
      if (2 !== $.args.length) {
        throw new Error("Expecting 2 arguments");
      }

      // Destructure the function arguments
      const [from, to] = $.args;

      // Generate a random number
      return Math.floor(Math.random() * (to - from + 1)) + from;
srcInputs: []
srcOutputs: []

$.current

{string}

Current state key.

$.previous

{string|null}

Previous state key or null if this is the entry state.

async $.fn( fnKey, fnArgs = [] )

Call a function (see the Functions tab).

@param {string} fnKey Function key
@param {array} fnArgs (optional) Function arguments; accessed with $.args

async $.llm( prompt )

Prompt the locally running large language model.

@param {string} prompt Prompt - up to 4096 characters long
@return {string} LLM response
@throws {Error} Throws an error if the LLM is not ready

$.log( message, status = "info" )

Append a message to the agent logs.

@param {any} message Message
@param {"info"|"success"|"warning"|"error"} status (optional) Status; default info

$.tick( name, amount = 1 )

Increment a named counter in the Status bar.
Up to 5 counters can be displayed at a time.

@param {string} name Counter name. The following strings are displayed as icons:
 "contact", "view", "like", "post", "repost", "comment",
 "upload", "download", "screenshot", "collect",
 "success", "warning"
@param {int} amount (optional) Strictly positive number; [1,1000]; default 1

$.stop( message = "", url = "" )

Stop the execution of the current state.
When resumed, the finite-state machine will start from the first state (the Entry Point 🏁).

@param {string} message (optional) Message displayed in the agent button instead of the agent name
@param {string} url (optional) Add button to open this URL in a new window; useful for bypassing security checks during login

$.pause( message = "", url = "" )

Pause the execution of the current state indefinitely.
When resumed, the current state will be re-executed from the start, not from the current line!

@param {string} message (optional) Message displayed in the agent button instead of the agent name
@param {string} url (optional) Add button to open this URL in a new window; useful for bypassing security checks during login

async $.sleep( ms )

Pause the execution of the current thread for a specified number of milliseconds.

@param {number} ms Sleep time in milliseconds

$.setTimeout( callback, ms )

Delays execution of a function by a specified number of milliseconds.

@param {function} callback JavaScript function
@param {number} ms The number of milliseconds to wait before executing the callback
@return {int} Timeout ID

$.clearTimeout( timeoutId )

Cancels a timeout previously established by $.setTimeout.

@param {function} timeoutId The identifier of the timeout to cancel, as returned by $.setTimeout

async $.globalEnvGet( envKey = null )

Environment globals: Get environment variable(s). Values are JSON serializable.
These values persit between runs but are reset on module install, fork or release.

@param {string|null} envKey (optional) Environment variable key or null for all values as a key-value object; default null
@return {object|any|null}

async $.globalEnvSet( envKey, envValue )

Environment globals: Set environment variable. Values must be JSON serializable.
These values persit between runs but are reset on module install, fork or release.

@param {string} envKey Environment variable key
@param {any|null} envValue Environment variable value; if null, the key is removed
@throws {Error} If total environment storage size exceeded 256kB for this agent
@return {boolean}

$.globalRunGet( runKey = null )

Run globals: Get global variable(s) for this run.
These values are reset before each run.

@param {string|null} runKey (optional) Run variable key or null for all values as a key-value object; default null
@return {object|any|null}

$.globalRunSet( runKey, runValue )

Run globals: Set global variable for this run.
These values are reset before each run.

@param {string} runKey Run variable key
@param {any|null} runValue Run variable value; if null, the key is removed
@return {boolean}

$.ioInputInt( ioKey )

IO: Get input integer.

@param {string} ioKey Integer input key
@return {int | null} Integer supplied by user or null if input is not of type integer

$.ioInputString( ioKey )

IO: Get input string.

@param {string} ioKey String input key
@return {string | null} String supplied by user or null if input is not of type string

$.ioInputBool( ioKey )

IO: Get input boolean.

@param {string} ioKey Boolean input key
@return {boolean | null} Boolean supplied by user or null if input is not of type boolean

async $.ioInputRow( ioKey, index = null )

IO: Get the next available table row and increment index internally.
Alternatively, get the row at the specified index.
Row keys are declared in the Inputs tab for this table input.

@param {string} ioKey Table input key
@param {int} index (optional) Table index; default null
@return {Object<string,string> | null} Current row or null if reached the end of the table or if input is not of type table

$.ioInputFiles( ioKey )

IO: Get input file paths.

@param {string} ioKey Files input key
@return {string[] | null} Input file paths or null if input is not of type files

async $.ioOutputInt( ioKey, int )

IO: Set output integer.
Subsequent calls override previous values.

@param {string} ioKey Integer output key
@param {int} int Integer
@return {boolean} True on success, false for invalid integer or if output is not of type integer

async $.ioOutputString( ioKey, string )

IO: Set output string.
Subsequent calls override previous values.

Warning: string will be truncated to 1024 characters.
If you need to store longer strings, use $.ioSaveText instead.

@param {string} ioKey String output key
@param {string} string String
@return {boolean} True on success, false for invalid string or if output is not of type string

async $.ioOutputBool( ioKey, boolean )

IO: Set output boolean.
Subsequent calls override previous values.

@param {string} ioKey Boolean output key
@param {boolean} boolean Boolean value
@return {boolean} True on success, false for invalid boolean or if output is not of type boolean

async $.ioOutputRow( ioKey, row )

IO: Append a row to output table.
Row keys are declared in the Outputs tab for this table output.

@param {string} ioKey Table output key
@param {Object<string,string>} row Row object
@return {boolean} True on success, false for invalid row object or if output is not of type table

async $.ioSaveText( ioKey, text, extension = "txt" )

IO: Save text to disk as new file.

Useful for saving arbitrary strings in custom formats like JSON, YAML, INI etc.
For strings that are shorter than or equal to 1024 characters, you can use $.ioOutputString.

@param {string} ioKey Files output key
@param {string} text Text to save
@param {string} extension (optional) File extension; default txt; must match one of the extensions defined in Outputs
@return {string | null} File path on success, null if download failed or if output is not of type files

async $.ioSaveDownload( ioKey, timeout = 600 )

IO: Capture the next downloaded file and save it to disk.

Useful for saving any file download, regardless of how it was trigerred.
Defer the download event with $.setTimeout() before calling $.ioSaveDownload.

@param {string} ioKey Files output key
@param {int} timeout (optional) Download timeout in seconds; default 600
@return {string | null} File path on success, null if download failed or if output is not of type files

async $.ioSaveUrl( ioKey, url, timeout = 600 )

IO: Capture the file stored at this URL and save it to disk.

Useful for saving files that are not available as links on page.

@param {string} ioKey Files output key
@param {string} url URL to download
@param {int} timeout (optional) Download timeout in seconds; default 600
@return {string | null} File path on success, null if download failed or if output is not of type files

async $.ioSaveRequest( ioKey, url, reqMethod = "GET", reqData = {}, reqHeaders = {}, reqJson = true, timeout = 600 )

IO: Capture the result of this fetch request and save it to disk.

Useful for saving the result of fetch requests made from the current domain/page.
For direct access to JSON or text responses, use $.doRequest instead.

@param {string} ioKey Files output key
@param {string} url URL to download
@param {string} reqMethod (optional) Request method; default GET
@param {object} reqData (optional) Request data; default {}
@param {object} reqHeaders (optional) Request headers; default {}
@param {boolean} reqJson (optional) JSON response; default true
@param {int} timeout (optional) Download timeout in seconds; default 600
@return {string | null} File path on success, null if download failed or if output is not of type files

async $.navLoad( url )

Navigation: Open URL and wait for the page to load.

@param {string} url URL; only http and https protocols are allowed
@return {boolean} True on success, false on failure
@throws {Error} Throws an error if page failed to load

async $.navReload( skipCache = false )

Navigation: Reload the current page.

@param {boolean} skipCache (optional) Reload skipping the cache; default false
@return {boolean} True on success, false on failure
@throws {Error} Throws an error if page failed to load

async $.navGoBack()

Navigation: Go backwards.

@return {boolean} True on success, false on failure
@throws {Error} Throws an error if page failed to load

async $.navGoForward()

Navigation: Go forwards.

@return {boolean} True on success, false on failure
@throws {Error} Throws an error if page failed to load

async $.navGetUrl()

Navigation: Get the URL of the current page.

@return {string}

async $.navGetTitle()

Navigation: Get the title of the current page.

@return {string}

async $.handleAlert()

Browser: Prevent the next window.alert() from bubbling.

Unhandled alert dialogs are automatically closed,
and their message is passed as a toast notification.

async $.handleConfirm( accept = true )

Browser: Prevent the next window.confirm() from bubbling, and either accept or reject it.

Unhandled confirmation dialogs are automatically accepted,
and their message is passed as a toast notification.

@param {boolean} accept (optional) Accept or reject the next confirmation message; default true

async $.handlePrompt( response = "" )

Browser: Prevent the next window.prompt() from bubbling, and answer it.

Unhandled prompts automatically return with their default value or an empty string,
and their message is passed as a toast notification.

@param {string} response (optional) Prompt response text

async $.doQuery( cssSelector, contains = null, parentElKey = null, fromScreenView = false )

Document: Find the first HTML element that matches the CSS selector and return its corresponding Element key.

@param {string} cssSelector Standard CSS selector
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@param {string} parentElKey (optional) Parent Element key; default null to search the entire Document
@param {boolean} fromScreenView (optional) Restrict results to elements placed from the current scroll position down; default false
@return {string|null} Element key on null on error

async $.doQueryAll( cssSelector, contains = null, parentElKey = null, fromScreenView = false )

Document: Find all HTML elements that match the CSS selector and return their corresponding Element keys.

@param {string} cssSelector Standard CSS selector
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@param {string} parentElKey (optional) Parent Element key; default null to search the entire Document
@param {boolean} fromScreenView (optional) Restrict results to elements placed from the current scroll position down; default false
@return {string[]} Array of Element keys

async $.doQueryParent( elKey, cssSelector = null, contains = null )

Document: Find the parent of this HTML element that matches the CSS selector and return its corresponding Element key.

@param {string} elKey Element key - obtained with $.doQuery
@param {string} cssSelector (optional) CSS selector for parent element; default null to stop at first ancestor
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@return {string|null} Element key on null on error

async $.doQuerySiblings( elKey, cssSelector = null, contains = null )

Document: Find the siblings of this HTML element that match the CSS selector and return their corresponding Element keys.

@param {string} elKey Element key - obtained with $.doQuery
@param {string} cssSelector (optional) CSS selector for sibling elements; default null to return all siblings
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@return {string[]} Element keys

async $.doQueryAt( left, top, cssSelector = null, contains = null )

Document: Find the first HTML element that matches the CSS selector at the specified coordinates,
and return its corresponding Element key.

@param {int} left Left coordinate in pixels
@param {int} top Top coordinate in pixels
@param {string} cssSelector (optional) CSS selector for element at coordinates; default null to return the topmost element
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@return {string|null} Element key on null on error

async $.doHighlight( elKey, scrollIntoView = false )

Document: Highlight an HTML Element in the viewport for 1 second.

@param {string} elKey Element key - obtained with $.doQuery
@param {boolean} scrollIntoView (optional) Scroll element into view before highlighting; default false

async $.doHighlightBox( box )

Document: Highlight a box in the viewport for 1 second.

@typedef {Object} Box
@property {int} left Left coordinate in pixels
@property {int} top Top coordinate in pixels
@property {int} width Width in pixels
@property {int} height Height in pixels

@param {Box} box Box - obtained with $.doGetBox

async $.doGetBox( elKey )

Document: Get the box of any HTML Element.

@typedef {Object} Box
@property {int} left Left coordinate in pixels
@property {int} top Top coordinate in pixels
@property {int} width Width in pixels
@property {int} height Height in pixels

@param {string} elKey Element key - obtained with $.doQuery
@return {Box|null} Element box or null on error

async $.doGetType( elKey )

Document: Get the type of an HTML Element.

@param {string} elKey Element key - obtained with $.doQuery
@return {string|null} Element type or null on error

async $.doGetValue( elKey )

Document: Get the value of an HTML Element. Supported elements:
- input (includes checkbox and radio)
- textarea
- select
Returns multiple values for checboxes and multi-select.

@param {string} elKey Element key - obtained with $.doQuery
@return {string|string[]|boolean|null} Value or null on error

async $.doGetAttribute( elKey, attr )

Document: Get a single HTML Element attribute.

@param {string} elKey Element key - obtained with $.doQuery
@param {string} attr HTML attribute (lowercase)
@return {string|null} Attribute value or null on error

async $.doGetAttributes( elKey, attrs = [] )

Document: Get all or multiple HTML Element attributes.

@param {string} elKey Element key - obtained with $.doQuery
@param {string[]} attrs (optional) HTML attributes (lowercase) or empty array for all; default []
@return {Object<string,string>} Map of attribute and value

async $.doGetContent( elKey, asHtml = false )

Document: Get the content of an HTML Element.

@param {string} elKey Element key - obtained with $.doQuery
@param {boolean} asHtml (optional) Use innerHTML instead of innerText; default false
@return {string|null} Element contents or null on error

async $.doGetVisible( elKey )

Document: Get whether HTML Element is visible on page.

@param {string} elKey Element key - obtained with $.doQuery
@return {boolean}

async $.doGetInViewport( elKey )

Document: Get whether HTML Element is even partially located in the viewport.

@param {string} elKey Element key - obtained with $.doQuery
@return {boolean}

async $.doGetViewportSize()

Document: Get the viewport size

@return {{width: int, height: int}}

async $.doClick( elKey, doubleClick = false )

Document: Click or double-click on HTML Element.
Automatically scroll to Element before action.

@param {string} elKey Element key - obtained with $.doQuery
@param {boolean} doubleClick (optional) Double-click; default false
@return {boolean} True on success, false on failure

async $.doClickAt( left, top, doubleClick = false )

Document: Click or double-click at coordinates in viewport.

@param {int} left Left coordinate in pixels
@param {int} top Top coordinate in pixels
@param {boolean} doubleClick (optional) Double-click; default false
@return {boolean} True on success, false on failure

async $.doHover( elKey )

Document: Move mouse over an HTML Element.
Automatically scroll to Element before action.

@param {string} elKey Element key - obtained with $.doQuery
@return {boolean} True on success, false on failure

async $.doHoverAt( left, top )

Document: Move mouse to coordinates in viewport.

@param {int} left Left coordinate in pixels
@param {int} top Top coordinate in pixels
@return {boolean} True on success, false on failure

async $.doHoverCenter()

Document: Move mouse just slightly outside of viewport center.

@return {boolean} True on success, false on failure

async $.doJiggle( radius = 50 )

Document: Jiggle the mouse at the current coordinates.

@param {int} radius (optional) Jiggle radius in pixels; [10,500]; default 50
@return {boolean} True on success, false on failure

async $.doScroll( amount, vertical = true )

Document: Scroll on page.

@param {int} amount Scroll amount in pixels
@param {boolean} vertical (optional) Vertical or Horizontal scroll; default true for vertical
@return {boolean} True on success, false on failure

async $.doScrollTo( elKey, marginTop = 0 )

Document: Scroll to HTML Element.

@param {string} elKey Element key - obtained with $.doQuery
@param {int} marginTop (optional) Top margin; default 0
@return {boolean} True on success, false on failure

async $.doType( elKey, text, replace = false, submit = false, speed = 50 )

Document: Type text to specified HTML element.
Automatically scroll to Element before action.
Skips typing if the Element is not editable.

To save time on large texts, the first part of the text is pasted,
and only the last 250 characters are typed one character at a time.

@param {string} elKey Element key - obtained with $.doQuery
@param {string} text Text to type
@param {boolean} replace (optional) Replace current text; default false to append text
@param {boolean} submit (optional) Press the Enter key at the end; default false
@param {int} speed (optional) Typing speed in characters per second; [25,250]; default 50
@return {boolean} Returns false if target element is not editable

async $.doTypeAt( left, top, text, replace = false, submit = false, speed = 50 )

Document: Type text at coordinates in viewport.

To save time on large texts, the first part of the text is pasted,
and only the last 250 characters are typed one character at a time.

@param {int} left Left coordinate in pixels
@param {int} top Top coordinate in pixels
@param {string} text Text to type
@param {boolean} replace (optional) Replace current text; default false to append text
@param {boolean} submit (optional) Press the Enter key at the end; default false
@param {int} speed (optional) Typing speed in characters per second; [25,250]; default 50
@return {boolean} True on success, false on failure

async $.doSelect( elKey, values )

Document: Select zero, one or more options, replacing previous selection.
Automatically scroll to Element before action.

@param {string} elKey Element key - obtained with $.doQuery
@param {string|string[]} values A single value or an array of values for <select miltiple/>
@return {boolean} True on success, false on failure

async $.doCheck( elKey, values )

Document: Check radio or checkbox values. The element's siblings must share the same name attribute.
Automatically scroll to Element(s) before action.

@param {string} elKey Element key - obtained with $.doQuery
@param {string|string[]} values A single value or an array of values
@return {boolean} True on success, false on failure

async $.doChooseFiles( elKey, filePaths )

Document: Choose files for <input type="file" /> HTML Element.
Automatically scroll to Element before action.

@param {string} elKey Element key - obtained with $.doQuery
@param {string|string[]} filePaths File path(s)
@return {boolean} True on success, false on failure

async $.doRequest( url, reqMethod = "GET", reqData = {}, reqHeaders = {}, reqJson = true, timeout = 600 )

Document: Make a fetch request from the current page.

Useful for JSON and simple text responses.
For large files or binary data use $.ioSaveRequest instead.

@param {string} url Request URL
@param {string} reqMethod (optional) Request method; default GET
@param {object} reqData (optional) Request data; default {}
@param {object} reqHeaders (optional) Request headers; default {}
@param {boolean} reqJson (optional) JSON response; default true
@param {int} timeout (optional) Request timeout in seconds; default 600
@return {any|string} JSON data if reqJson is true, string otherwise
@throws {Error} Throws an error if request failed or aborted

async $.doAwaitPresent( cssSelector, contains = null, parentElKey = null, timeout = 60 )

Document: Wait for an Element to be present in the DOM.

@param {string} cssSelector Standard CSS selector
@param {string} contains (optional) Text contained by Element (case insensitive); default null for no restrictions
@param {string} parentElKey (optional) Parent Element key; default null to search the entire Document
@param {int} timeout (optional) Timeout in seconds; default 60
@return {string[]|false} Array of Element keys or false on timeout

async $.doAwaitNotPresent( elKey, timeout = 60 )

Document: Wait for an Element to be removed from the DOM.

@param {string} elKey Element key - obtained with $.doQuery or $.doAwaitPresent
@param {int} timeout (optional) Timeout in seconds; default 60
@return {boolean} True on success, false on timeout

async $.doAwaitVisible( elKey, timeout = 60 )

Document: Wait for an Element to become visible to the user (display, visibility, opacity).

@param {string} elKey Element key - obtained with $.doQuery or $.doAwaitPresent
@param {int} timeout (optional) Timeout in seconds; default 60
@return {boolean} True on success, false on timeout

async $.doAwaitNotVisible( elKey, timeout = 60 )

Document: Wait for an Element to become invisible to the user (display, visibility, opacity).

@param {string} elKey Element key - obtained with $.doQuery or $.doAwaitPresent
@param {int} timeout (optional) Timeout in seconds; default 60
@return {boolean} True on success, false on timeout