Tools

Each agent has access to a set of tools that the LLM can invoke during its agentic loop. Tools are defined as OpenAI-compatible function calling schemas and executed server-side on the agent VM.

Tool reference

bash

Execute a shell command and return stdout, stderr, and exit code.

Parameter	Type	Required	Description
command	string	yes	The bash command to execute
timeout	integer	no	Timeout in seconds (default 60, max 300)

Output is truncated at 30,000 characters (split evenly between start and end with a truncation notice in the middle). Commands that exceed the timeout are killed and return a timeout message.

Safety guards: Before execution, every command is checked against a set of deny patterns. Blocked commands return an error without being executed. See Security model below.

read_file

Read a file and return its contents with line numbers.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
offset	integer	no	Line number to start from (1-based)
limit	integer	no	Maximum number of lines to read

Output format is <line_number>\t<content> per line, matching common editor conventions. Output is truncated at 30,000 characters.

write_file

Write content to a file, creating parent directories as needed.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
content	string	yes	The content to write

edit_file

Find and replace an exact string in a file (first occurrence only).

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
old_string	string	yes	The exact string to find
new_string	string	yes	The replacement string

Returns an error if old_string is not found in the file. Only the first occurrence is replaced.

list_dir

List contents of a directory with type prefixes.

Parameter	Type	Required	Description
path	string	no	Directory path (defaults to workspace root)

Output format uses [dir] and [file] prefixes, sorted with directories first.

web_fetch

Fetch a URL and return its text content.

Parameter	Type	Required	Description
url	string	yes	URL to fetch (http or https)

HTML content is automatically stripped of tags and decoded. JSON responses are pretty-printed. Output is truncated at 50,000 characters. Requests follow up to 5 redirects and time out after 30 seconds.

web_search

Search the web using LibertAI Search. Returns titles, URLs, and snippets.

Parameter	Type	Required	Description
query	string	yes	The search query
count	integer	no	Number of results, 1-10 (default 5)

Requires a valid LIBERTAI_API_KEY. The search aggregates results from multiple engines (Google, Bing, DuckDuckGo). Failed engines are noted in the output.

generate_image

Generate an image from a text prompt using LibertAI’s image generation API.

Parameter	Type	Required	Description
prompt	string	yes	Text description of the image
size	string	no	Dimensions as "WxH" (default "1024x1024", max 1024 per side, multiples of 16)
steps	integer	no	Generation steps (default 8 for speed, use 14 for higher quality or text readability)

The generated image is saved to workspace/images/<uuid>.png and automatically sent to the user.

send_file

Send a file from the workspace to the user.

Parameter	Type	Required	Description
path	string	yes	Path to the file (relative to workspace or absolute within workspace)
caption	string	no	Optional caption

Files are validated against the workspace boundary and sensitive file list. Maximum file size is 50 MB.

spawn

Spawn a background subagent to work on a task asynchronously. Not available to subagents (prevents recursive spawning).

Parameter	Type	Required	Description
task	string	yes	Task description for the subagent
label	string	no	Short label for the task (defaults to first 50 chars of task)
persona	string	no	System prompt override for the subagent
timeout	integer	no	Wall-clock timeout in seconds (default 300, max 600)

Subagents run with a restricted tool set (no further spawning) and a maximum of 15 tool iterations. Results are delivered as pending messages. Up to 5 subagents can run concurrently per chat.

Security model

Workspace boundary

All file operations (read_file, write_file, edit_file, list_dir, send_file) enforce a strict workspace boundary. Paths are resolved against the workspace root and checked after symlink resolution. Any path that escapes the workspace directory is rejected with a PathSecurityError.

Relative paths are treated as relative to the workspace. Absolute paths must still fall within the workspace boundary.

Sensitive file protection

Certain filenames are blocked from being read or served, even within the workspace:

• .env — Contains secrets and API keys
• agent.db, agent.db-shm, agent.db-wal — Internal SQLite database files

Bash deny patterns

The bash tool checks every command against a set of regex deny patterns before execution. Matching commands are blocked immediately. The patterns prevent:

Destructive system commands:

• rm -rf / or rm -rf ~ — Recursive deletion of root or home
• mkfs, format, diskpart — Disk formatting
• dd if= — Raw disk writes
• > /dev/sd* — Writing to block devices
• shutdown, reboot, poweroff, halt — System shutdown
• Fork bombs (:(){ ... };:)
• systemctl stop baal-agent — Stopping the agent service
• kill -9 1 — Killing PID 1

Secret exfiltration:

• env, printenv, set — Environment variable dumps
• export -p, declare -x — Export listing
• /proc/*/environ — Process environment files
• Any .env file access
• /run/secrets — Container secrets

File size limits

• Tool output: 30,000 characters (truncated with middle section removed)
• Web content: 50,000 characters
• File uploads/sends: 50 MB