Manage Apps Tool

​

What it does

The Manage Apps tool lets agents create and manage persistent interactive pages inside Aster. When a user asks for a dashboard, report, or data visualization, the agent can build one that lives at a permanent URL — not just a one-time chat response. See Apps for the full user-facing feature overview.

​

When to use it

Add this tool to agents that:

• Analyze data from integrations (GA4, Salesforce, Snowflake, etc.) and need a way to present results beyond chat
• Build recurring reports that users want to bookmark and revisit
• Create multi-section views with charts, tables, KPIs, and tabs
• Need to update an existing view with fresh data

​

Parameters

​

Actions

​

create

Build and publish a new app in a single call. Required: name, source_tsx. Optional: description, snapshot_data.

​

update

Update an existing app’s content, data, or metadata. A new version is created internally — the URL stays the same. Required: app_id. Optional: name, description, source_tsx, snapshot_data.

​

list

Returns all apps in the organization.

​

get

Returns an app’s metadata and current source code — but not its snapshot data. To read or edit an app’s data (or faithfully rebuild it), use load_to_sandbox, which loads the full project (including data/snapshot.json) into the sandbox where execute_python can read it. Required: app_id.

​

delete

Removes an app. Required: app_id.

​

set_lock

Locks or unlocks an app. While an app is locked, only its author or an org admin can update, delete, or unlock it — any other agent that attempts update, delete, or set_lock gets an error and should tell the user the app is locked rather than retry. Apps are unlocked by default. Only the app’s author or an org admin can call set_lock. Required: app_id, locked (true to lock, false to unlock).

​

load_to_sandbox

Loads an existing app’s source, data, and assets into the code execution sandbox for editing. After loading, the agent can use execute_python to modify files, then call publish_from_sandbox to publish the changes. Pass a version_id to load a historical version instead of the current one — this hydrates that version’s source and its snapshot data and assets, which is the full-fidelity restore path: load the old version, then publish_from_sandbox to republish it as a new version. Required: app_id. Optional: app_dir (defaults to /home/user/aster-apps/app-{app_id}), version_id (defaults to the current version).

​

publish_from_sandbox

Reads an app project from the sandbox, validates it, compiles it, and publishes it. The sandbox directory must contain an aster-app.json manifest. Required: app_dir. Optional: app_id (omit to create a new app, provide to update an existing one).

​

list_versions

Returns an app’s version history — every publish creates a version, and all of them are preserved. Each entry includes the version id, when it was published, whether it’s the current version, the bundle hash, source file list, and asset count. Returns the 50 most recent versions; older versions remain fetchable by id via get_version. Required: app_id.

​

get_version

Returns a specific historical version’s complete source code — the entry component plus the full source tree, but not its snapshot data. Use it to see how an app’s code changed between versions. To restore a historical version, use load_to_sandbox with the version_id instead — for data-driven apps, versions often differ only in snapshot data, so a faithful restore needs the data, not just the source. Required: app_id, version_id.

​

Available libraries

Apps can use these libraries in their source code: All Tailwind CSS classes are supported, including arbitrary values.

​

Sandbox project workflow

For complex apps with multiple files, generated assets, or iterative editing:

1. Agent uses execute_python to build files in /home/user/aster-apps/{slug}/
2. Agent writes an aster-app.json manifest:
   {
     "name": "Pipeline Dashboard",
     "entry": "src/App.tsx",
     "snapshot": "data/snapshot.json",
     "description": "Weekly pipeline overview",
     "assetsDir": "assets"
   }
   
3. Agent calls manage_apps with action: "publish_from_sandbox"

To edit an existing app: call load_to_sandbox first, modify files with execute_python, then publish_from_sandbox.

​

Common use cases

​

Dashboard from live data

“Pull our GA4 traffic data and build a dashboard with trends by channel, top pages, and device split”

​

Updating an existing app

“Refresh the pipeline dashboard with this week’s numbers” The agent re-queries the data source and calls update with new snapshot data.

​

Complex multi-section app via sandbox

“Build a detailed analytics app with separate sections for overview, queries, pages, and opportunities — include downloadable CSV exports” The agent builds multiple component files and data assets in the sandbox, then publishes the whole project.