Manage Apps Tool

Give your agents the ability to create persistent dashboards, reports, and interactive views

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

Parameter	Type	Required	Description
action	string	Yes	The operation to perform (see Actions below)
app_id	integer	Varies	The app to read, update, delete, lock, or load
version_id	integer	For get_version	The historical version to fetch or load — ids come from list_versions. Also accepted by load_to_sandbox to load a historical version
app_dir	string	Varies	Sandbox directory path for project-based workflows
name	string	For create	Display name shown in the app listing and header
description	string	No	What the app shows — displayed in the listing
source_tsx	string	For create/update	The component source code. Must export a default component
snapshot_data	object	No	JSON data the app renders, accessed via useAppData()
locked	boolean	For set_lock	true to lock the app, false to unlock it

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:

Library	What it provides
@aster/sdk	useAppData() — access the snapshot data
@aster/ui	UI components (Card, Badge, Button, Table, Tabs, Progress, Separator, ScrollArea, Tooltip) and cn() utility
recharts	Charts — LineChart, BarChart, PieChart, AreaChart, ComposedChart, etc.
lucide-react	Icons
date-fns	Date formatting and manipulation

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.