Skip to main content
connic
Apps

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.

Last updated

How it works

  1. List the app under apps in the agent's YAML. The agent gets the app_publish tool in every run where an entry's condition holds; it isn't listed under tools. 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.
  2. The agent writes static files into a folder with the file tools, with an index.html at the top of the folder.
  3. It calls app_publish with the app and the folder and gets the instance's URL, https://<app host>/i/<instance id>/.
  4. 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.
agents/analyst.yaml
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 result
apps/reports.yaml
name: 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.groups

Agent 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.

FieldTypeStatusDescription
appstringRequiredThe app's key, the name of its apps/<key>.yaml file. Each app can be listed once.
conditionstringOptionalOffer 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_daysintegerOptionalDelete 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.
userstringOptionalA 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.

app_publish result
{
  "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.

tools/reports.py
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.

reports/drafts/q3/index.html
<!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_days after 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 the apps/ 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.