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

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`/`restore_version`	The historical version to fetch, restore, or load — ids come from `list_versions`. Also accepted by `load_to_sandbox` to load a historical version
`change_summary`	string	When code changes	One line saying what changed in this version, shown in the app’s version history. Required for `publish_from_sandbox` when the compiled code changes. Optional for data-only refreshes, `update` and `restore_version`
`keep_current_data`	boolean	No	For `restore_version`: restore the version’s code and layout but keep the app’s current data
`app_dir`	string	Varies	Sandbox directory path for project-based workflows
`name`	string	No	Display name shown in the app listing and header
`description`	string	No	What the app shows — displayed in the listing
`snapshot_data`	object	No	For `update`: JSON data the app renders, accessed via `useAppData()`. Replaces the app’s data; its code carries forward
`tags`	string[]	For `set_tags` and creating an app	Shared tag names. A `publish_from_sandbox` that creates an app requires one or two names for what the app is for; reuse the organization’s names where they fit. On `set_tags`, replaces the full set; `[]` clears it. Up to 50 names, each 1–50 characters after trimming
`locked`	boolean	For `set_lock`	`true` to lock the app, `false` to unlock it
`app_params`	string	No	For `export_pdf`/`export_png`: URL params to render the app with (e.g. `region=West&tab=2`), so the export captures a filtered view rather than the default. Requires the app to read `useAppParams()`
`orientation`	string	No	For `export_pdf`: `landscape` (default) or `portrait`
`title`	string	No	For `export_pdf`/`export_png`: filename for the generated file — a timestamp and extension are appended. Defaults to the app’s name
`all_tabs`	boolean	No	For `export_pdf`: `true` exports every tab of a multi-tab app into one combined PDF. Defaults to `false` (default view only). Only standard tab components are walked

Actions

update

Changes an existing app’s name or description, and/or replaces its data. New data publishes a new version with the app’s code, layout, assets and manifest carried forward unchanged — the URL stays the same. To change the app’s code, use load_to_sandbox, edit the files, then publish_from_sandbox. Required: app_id. Optional: name, description, snapshot_data (or snapshot_file).

list

Returns all apps in the organization.

get

Returns an app’s metadata and its entry file’s source (entrySource) — 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.

status

Read the current DB publication pointer, R2 manifest metadata and existing sandbox changes without loading/replacing files or creating a sandbox. Use when working or published state is unclear, including after context loss or an uncertain publication result. Returns local file changes, remote divergence, bounded activity observations and exact record paths. Missing/unavailable evidence means unknown. Observations across DB/R2/E2B are not atomic; this is not a publication lock or durable operation ledger. Required: app_id. Optional: app_dir (otherwise discovers recorded working copies), version_id (checks whether that version is currently active; a noncurrent row alone cannot prove a past commit or rollback). /home/user/.aster/README.md explains the local platform activity log. Arbitrary Python/bash edits are compared at resource boundaries; they are not logged command by command. Ordinary edits do not require status/log checks.

delete

Removes an app. Required: app_id. Lists the shared organization tag catalog, with the same IDs and names used by agents and apps. agentCount and appCount count all assignments, including archived resources, for safe deletion confirmation.

set_tags

Replaces one app’s tags, creating names as needed and reusing existing names case-insensitively. Use team, purpose, or topic names. Tags appear as a filter on the Apps page; list and get include each app’s tags. Locked apps require the author or an org admin to change tags. Required: app_id, tags.

{"action":"set_tags","app_id":123,"tags":["Portfolio","Finance"]}

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, so it can be edited before republishing. To put a past version back unchanged, use restore_version. Loading the same revision preserves local edits and deletions. Occupied destinations or changed revisions return a conflict; use overwrite: true for deliberate replacement or choose another directory. Unrelated app scratch files are preserved. Required: app_id. Optional: overwrite, 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. This is how every app is created and how its code changes. An aster-app.json manifest is optional — omit it and the entry is inferred (preferring src/App.tsx) with an empty snapshot. Required: app_dir. Optional: app_id (omit to create a new app, provide to update an existing one).

Declaring what the app reads

If the app reads live data or shows knowledge base files, its aster-app.json must say which:

{
  "entry": "src/App.tsx",
  "dataStores": [952],
  "knowledgeBases": [546]
}

dataStores — every data store the app reads with useLiveTable / useDataStore.
knowledgeBases — every file knowledge base it shows documents from (Citation / useCitation, kb: file refs, useKbSearch / useKbFiles).

A public share link can read exactly what is declared, so declare only what the app reads: publishing refuses a declaration the code doesn’t use. If the code reads something it doesn’t declare, the publish goes through with a warning, but the app can’t be shared publicly until it’s declared, and once an app has a live share link, publishing refuses that too. Data-only publishes, update and restore_version carry the declaration forward. Full sandbox publication captures the selected files and transfers changed content while reusing unchanged stored files. The agent does not maintain hashes or patch lists. data_only: true explicitly publishes only the packaged snapshot, carrying forward the current code/assets observed during publication. Live structured DB row writes use their own write surfaces and do not require app publication. The response includes:

changed_code — whether the compiled bundle differs from the current version. false does not rule out snapshot or asset changes, which can affect rendering.
snapshot_diff — an advisory shape diff against the previous snapshot, flagging dropped, renamed, reshaped, or emptied keys. This is the most common cause of a tab going silently blank after a refresh.
render — the published version’s first screen, rendered in headless Chromium after activation (on update with data and restore_version too). status is ok, error (the app threw on mount or can’t load — users opening it hit the same thing), timeout (no verdict within the render’s time limit — often a slow data load, not a broken app), or superseded (another publish landed first). On success the screenshot is attached to the conversation and also becomes the app’s tile image on the Apps page. The version is already live either way; a failed render never fails the publish.

Before creating an app or changing its code or layout, the agent loads the building-on-aster skill — it covers project structure, the snapshot data contract, and a render check that catches blank or crashed tabs before publishing. A data-only refresh (rebuilding data/snapshot.json with the source untouched) skips the skill.

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, its per-app number (v1, v2, …), when it was published, whether it’s the current version, its change_summary, who published it, and whether its code changed from the version before (false means a data refresh). 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 restore_version. Required: app_id, version_id.

restore_version

Puts a past version back live by publishing it as a new version, so nothing is deleted and a restore can itself be undone the same way. By default the version comes back exactly as it was, code and data. Pass keep_current_data: true to take only its code and layout and keep the app’s current data. Restoring follows the same lock rule as any edit. People can also do this from Version history in the app’s menu. Required: app_id, version_id. Optional: keep_current_data, change_summary (defaults to “Restored vN”).

Available libraries

Apps can use these libraries in their source code:

Library	What it provides
`@aster/sdk`	`useAppData()` — access the snapshot data; `useAppParams()` — read/write URL params; `useCitation()` — open a knowledge base source
`@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
`d3-geo` + `topojson-client`	SVG geographic maps — choropleths, bubble/dot maps (no tile basemaps)

All Tailwind CSS classes are supported, including arbitrary values.

useAppData().data is always present — no loading/null guard needed. Still guard arrays before .map/.reduce (e.g. (data.rows || []).map(...)) for empty refreshes.

Every published app has a native Export button (top of the app) that produces a PDF or PNG — the current view, or, for tabbed apps, all tabs combined into one PDF. Don’t build your own PDF / print / download-image logic into an app — the platform handles it.For tabbed apps, build the tabs with the @aster/ui Tabs component (not hand-rolled useState switching) so the all-tabs export can capture each tab; custom tab bars only export the view that’s currently visible.

URL parameters and deep links

An app’s query string belongs entirely to the app, so an agent can link a user straight to a particular view — https://www.asteragents.com/apps/216?region=West&tab=2. Read it with useAppParams():

import { useAppParams } from '@aster/sdk';

const [params, setParams] = useAppParams();
const region = params.region ?? 'All';          // values are strings, and may be absent
<button onClick={() => setParams({ region: 'West' })}>West</button>   // null clears a key

setParams merges into the URL, so a user who filters in-app gets a link they can share — and the Export button produces a PDF of that same filtered view. Agents can export a filtered view directly via the app_params parameter.

Use the hook, never window.location.search. A direct read works in the viewer but renders the app’s unfiltered default in PDF/PNG exports. Params filter within the published snapshot — they can’t fetch different data.

Sandbox project workflow

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

Agent uses execute_python to build files in /home/user/aster-apps/{slug}/

Agent writes an aster-app.json manifest:

{
  "name": "Pipeline Dashboard",
  "entry": "src/App.tsx",
  "snapshot": "data/snapshot.json",
  "description": "Weekly pipeline overview",
  "assetsDir": "assets"
}

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. Publication confirmation is stored on app_version in the same transaction that activates it. status returns recent confirmed publications; pass version_id or operation_id to inspect a particular attempt. A confirmed noncurrent version was published and subsequently superseded. Older versions without confirmation remain unknown. Replaying the same harness operation returns its recorded result without republishing; a new tool call is a new operation.

Get Started

Build Agents

Run & Share

Built-in Tools

Integrations

Organization Settings

Resources

What it does

When to use it

Parameters

Actions

update

list

get

status

delete

set_tags

set_lock

load_to_sandbox

publish_from_sandbox

Declaring what the app reads

list_versions

get_version

restore_version

Available libraries

URL parameters and deep links

Sandbox project workflow

Common use cases

Dashboard from live data

Updating an existing app

Complex multi-section app via sandbox

​What it does

​When to use it

​Parameters

​Actions

​update

​list

​get

​status

​delete

​list_tags

​set_tags

​set_lock

​load_to_sandbox

​publish_from_sandbox

​Declaring what the app reads

​list_versions

​get_version

​restore_version

​Available libraries

​URL parameters and deep links

​Sandbox project workflow

​Common use cases

​Dashboard from live data

​Updating an existing app

​Complex multi-section app via sandbox

What it does

When to use it

Parameters

Actions

update

list

get

status

delete

list_tags

set_tags

set_lock

load_to_sandbox

publish_from_sandbox

Declaring what the app reads

list_versions

get_version

restore_version

Available libraries

URL parameters and deep links

Sandbox project workflow

Common use cases

Dashboard from live data

Updating an existing app

Complex multi-section app via sandbox