Docs

Sdk

The Canvas App SDK enables you to build interactive applications that run inside the Agentastic launcher. Canvas apps have access to AI capabilities, the file system, network, and more through a secure bridge API.

What are Canvas Apps?

Canvas Apps are lightweight, sandboxed applications that render in a WebView within the Agentastic launcher. They can:

  • Make LLM calls - Request AI completions with custom prompts
  • Display rich UI - Use HTML, CSS, and JavaScript for interactive interfaces
  • Access tools - Leverage Agentastic's built-in tools like file operations, calendar, etc.
  • Communicate - Send and receive messages via the bridge API

App Types

Declarative Apps (ViewSpec)

Define your UI using a simple YAML structure. Perfect for forms, wizards, and simple tools.

id: hello-world
name: Hello World
view_spec:
  type: container
  children:
    - type: heading
      content: "Hello, Canvas!"
    - type: input
      name: user_name
      label: "Your Name"
    - type: button
      label: "Greet Me"
      action: greet

Packaged Apps (HTML)

Build with full HTML, CSS, and JavaScript for complex applications.

my-app/
├── manifest.yaml
├── index.html
├── styles.css
└── app.js

Quick Example

Here's a minimal Canvas app that greets the user with an AI-generated message:

manifest.yaml:

id: greeter
name: AI Greeter
version: 1.0.0
entrypoint: index.html
permissions:
  - llm

index.html:

<!DOCTYPE html>
<html>
<head>
  <title>AI Greeter</title>
  <script src="agentastic://sdk/bridge.js"></script>
</head>
<body>
  <input type="text" id="name" placeholder="Enter your name">
  <button onclick="greet()">Greet Me</button>
  <div id="response"></div>

  <script>
    async function greet() {
      const name = document.getElementById('name').value;
      const result = await Agentastic.llm.ask({
        user: `Generate a friendly, creative greeting for ${name}`,
        model: 'gpt-4.1-mini'
      });
      document.getElementById('response').textContent = result;
    }
  </script>
</body>
</html>

SDK Namespaces

The Canvas App SDK provides several namespaces:

NamespacePurpose
Agentastic.llmAI completions and streaming
Agentastic.uiToasts, modals, theme, and window control
Agentastic.agentContext, tool registration, and conversation injection
Agentastic.ipcInter-app communication
Agentastic.fsSandboxed file system operations
Agentastic.netNetwork requests
Agentastic.contextRuntime environment information

New in v0.2.0

Agent Namespace Enhancements:

  • agent.sendMessage() - Inject messages into the conversation as user or assistant
  • agent.setInput() - Populate the input field without sending
  • agent.unregisterTool() - Remove previously registered tools
  • agent.onThinking() - Subscribe to thinking state changes

UI Namespace Enhancements:

  • ui.openExternal() - Open URLs in the default browser
  • ui.setHeight() / ui.setSize() - Control app dimensions
  • ui.requestExpand() / ui.requestCollapse() - Toggle fullscreen mode
  • ui.onDisplayModeChange() - React to display mode changes

Context API:

  • Access runtime environment via Agentastic.context - locale, platform, color scheme, display mode, and more

Response Visibility Scoping:

  • Control what data is visible to AI models vs. your app only
  • Configure via responseScoping in manifest actions

Filesystem Security

Canvas apps have sandboxed filesystem access:

  • App directory - Always accessible at ~/Library/Application Support/agentastic/apps/<app-slug>/
  • External paths - Require explicit permissions in manifest.yaml
  • System paths - Always blocked (/System, /private, etc.)
# Example: Request access to user's Documents folder
permissions:
  filesystem:
    read:
      - ~/Documents/MyApp
    write:
      - ~/Documents/MyApp

See the Filesystem API documentation for details.

Getting Started

  1. Create a manifest - Define your app's metadata and permissions
  2. Build your UI - Use ViewSpec YAML or custom HTML/JS
  3. Connect the bridge - Import the SDK to access Agentastic features
  4. Test locally - Use the developer tools to debug
  5. Package and deploy - Distribute your app

Next Steps