Instances
Agents publish pages, such as a report with charts, as instances of an app. Each instance has its own URL on the app's host and uses the app's sign-in and access rules.
On this page
How it works
- List the app under
appsin the agent's YAML. The agent gets theapp_publishtool in every run where an entry's condition holds; it isn't listed undertools. The tool describes each app to the agent as it is deployed: its Content-Security-Policy, the files it accepts, the data API and the app's access rules. The agent's prompt only needs to say what the pages are for. - The agent writes static files into a folder with the file tools, with an
index.htmlat the top of the folder. - It calls
app_publishwith the app and the folder and gets the instance's URL,https://<app host>/i/<instance id>/. - Visitors open the URL like any page of the app: with the app's sign-in, its data API under its access rules, and its connectors.
name: analyst
model: connic/gpt-5.6-terra
description: "Answers questions about sales and shows them as reports"
system_prompt: |
When a chart or table helps, build a page in reports/drafts/<topic>/ with
index.html and publish it with app_publish. Share the returned url.
apps:
- app: reports
condition: context.user.role != null # optional; same grammar as conditional tools
max_age_days: 90 # optional; without it, instances stay until deleted
user: context.user # optional; adds embed_url to the resultname: Reports
instances_only: true # only /i/<instance id>/ pages; build becomes optional
build: # optional base build with your components and styles
command: npm run build
output: dist
auth:
mode: oidc
issuer: ${REPORTS_ISSUER}
client_id: ${REPORTS_CLIENT_ID}
client_secret: ${REPORTS_CLIENT_SECRET}
access:
database:
sales:
read: doc.region in user.groupsAgent configuration
Each entry under apps names one app. Two agents can publish to the same app with different settings. Only LLM agents take apps, and every app they list must have a file in apps/ and be deployed to the agent's environment, or the deploy fails.
| Field | Type | Status | Description |
|---|---|---|---|
| app | string | Required | The app's key, the name of its apps/<key>.yaml file. Each app can be listed once. |
| condition | string | Optional | Offer the app only when this expression is true for the run. Uses the conditional tools grammar. When no entry holds, the run has neither app_publish nor app_preview. |
| max_age_days | integer | Optional | Delete the instances this agent publishes this many days after their first publish. Publishing again doesn't extend it. Without it, instances stay until someone deletes them. |
| user | string | Optional | A context.<path> holding the end user: an ID, or an object with id and optionally email, name, and groups, usually set by middleware. app_publish then also returns an embed link signed in as that user. When the path holds nothing in a run, the result has no embed link. |
Publish
app_publish takes app, one of the apps the run offers, folder, a folder in Files, and optionally instance, the ID of an instance to replace. The folder's files keep their paths below it, so reports/drafts/q3/charts/sales.svg is served at /i/<instance id>/charts/sales.svg. The agent can only publish files its access rules let it read.
{
"instance": "5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13",
"url": "https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/",
"version": 1,
"expires_at": "2027-02-18T09:30:00Z",
"embed_url": "https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/?connic_embed=..."
}expires_at is null without max_age_days. The URL uses the app's custom domain when the connic.app address is turned off.
To change an instance, the agent writes the new files and publishes again with instance. All files are replaced, the URL stays the same, and version goes up by one. The instance must belong to the same app.
With app_publish the agent also gets app_preview. It opens a page published in the same run, through its embed link when there is one, and returns a screenshot and the errors and warnings the page logged, such as files its Content-Security-Policy blocked. The agent fixes what it sees and publishes again. Previews use the run's browser and count as browser usage.
The folder may contain the same file types as app sources, and an instance's files together can be as large as an app's build output on the project's plan, with up to 16 MiB per file and 20,000 files. A folder without index.html, with another file type, or over the size returns an error the agent sees, and nothing changes.
From custom code
Tools and middleware can publish with connic.tools.app_publish for any app the agent lists under apps. It takes the same arguments and returns the same result.
from connic.tools import app_publish
async def publish_report(topic: str) -> str:
"""Publish the report draft for a topic and return its URL."""
result = await app_publish("reports", f"reports/drafts/{topic}")
return result["url"]Base build
Instances live on the app's host, so their pages can load the files of the app's own build by absolute path. Put your components, styles, and chart libraries in the app's build, and the agent only writes the page that uses them. That keeps the pages in your design and the agent's output short.
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="/assets/reports.css">
<script type="module" src="/assets/reports.js"></script>
</head>
<body>
<sales-chart region="emea" months="12"></sales-chart>
</body>
</html>Instances get the app's Content-Security-Policy. With the default, a page loads scripts, styles, and images only from the app's host, so the agent's pages can't pull code from other sites unless content_security_policy allows them.
Instances only
With instances_only: true in apps/<key>.yaml, the app serves only its instances: every other page answers 404. The base build's other files, such as scripts, styles, fonts, and images, stay reachable for the instances. build becomes optional; without it, the app has no base build and no source folder in apps/.
Serving
/i/<instance id>/ serves the instance's index.html, and paths below it follow the same rules as the app's own serving, inside the instance. Browsers check an instance's files on every load, so a new version shows up right away. An instance that doesn't exist, has expired, or was deleted answers 404.
Lifetime and storage
- An instance stays until someone deletes it, or until
max_age_daysafter its first publish. Instances outlive the session and the run that created them, so links in old conversations keep working. - Deleting an instance removes its files and ends its embed links.
- Instances follow their app: a retired app stops serving them, and they're back when a deployment declares the app again. Deleting the environment deletes them.
- There is no limit on the number of instances. connic keeps a copy of each instance's files in Files under
apps/<key>/<instance id>/, where it counts as Files storage. Apps manage theapps/folder: its files can be read, listed, and downloaded, but not uploaded, moved, renamed, edited, or deleted through Files.
In the dashboard
The Instances tab of an app lists its instances with their link, the agent that published them, when they were created and expire, and their size. Seeing them takes View apps, and deleting one takes Manage apps. connic MCP offers the same with list_app_instances and delete_app_instance.