Apps Overview

Declare an app

Each file in apps/ declares one app, and a folder with the same name holds its sources. The file name without .yaml is the app's key: apps/portal.yaml builds from apps/portal/.

my-agent-project/
├── agents/
├── connectors/
│   └── portal-chat.yaml
└── apps/
    ├── portal.yaml          # the app's settings; the file name is its key
    └── portal/              # the app's sources
        ├── package.json
        ├── package-lock.json
        └── src/

name: Support portal              # optional, defaults to the file name
build:
  command: npm run build
  output: dist                    # folder with index.html, inside apps/portal/
auth:                             # optional; omit it to set sign-in in the dashboard
  mode: oidc
  issuer: ${PORTAL_ISSUER}
  client_id: ${PORTAL_CLIENT_ID}
  client_secret: ${PORTAL_CLIENT_SECRET}
  allowed_domains: [example.com]
connectors:                       # apps_only connectors the app calls
  - portal-chat
access:                           # data the browser may use; everything else is denied
  database:
    tickets:
      read: doc.author_id == user.id
      insert: true
      set:
        author_id: user.id
environments:                     # omit to deploy to every environment
  Staging:
    auth:
      mode: connic
  Production:
    domain: portal.example.com
dev:                              # connic dev environments the list doesn't name
  auth:
    mode: connic

Files sit directly in apps/ and use the .yaml extension. A file name starts with a letter or digit, contains only letters, digits, -, and _, and has at most 100 characters. Every file needs its source folder, and every folder in apps/ needs its file. connic lint checks the files, their rules, and the connectors they list offline, and connic deploy runs it first.

Environments and overrides

Without environments, every environment gets the app with the same settings. With it, only the listed environments do. Names must match exactly, and a name that doesn't exist in the project fails the deploy. Production: {} deploys the file unchanged. Each environment gets an app of its own, with its own URL, sign-in, and stats.

An override can set name, auth, connectors, domain, content_security_policy, lookups, and access. Each replaces the whole value from the top of the file: auth in Staging above replaces every OIDC setting, and an access override replaces all rules. To remove domain, content_security_policy, lookups, or access in one environment, set it to null there. build is the same in every environment.

dev takes the same fields and applies to every connic dev environment that environments doesn't name, quick tests included. With environments, those dev environments get the app only when dev is set; dev: {} uses the top of the file unchanged. Dev environments have Variables of their own, so the example above signs in with connic accounts there instead of reading the OIDC Variables.

Variables

${NAME} reads a Variable of the target environment in domain and in issuer, client_id, and client_secret of auth. connic resolves them when the deploy starts, and a missing Variable fails the deploy. client_secret must be a single ${NAME} reference.

Build commands can't use ${NAME}, and Variables aren't available during the build. An app that behaves differently per environment reads /_connic/config.json at runtime.

Build

Any framework that writes a static folder with an index.html works, such as Vite with React, Vue, Svelte, or Solid, Angular, Astro, Next.js with output: "export", SvelteKit with adapter-static, or Nuxt with nuxt generate. connic serves the files as they are, so server rendering, API routes, and server middleware don't run. Agents behind connectors and the data API do that work.

Each deploy builds its apps in a Node.js image of the version in build.node, as an unprivileged user and with CI=true. It copies package.json and the lockfile, runs the install command, copies the rest of apps/<key>/, runs build.command, and checks that build.output contains index.html. pnpm and yarn run through Corepack. The build output is part of the deployment log, and a failed build fails the deploy. Every deployment keeps its own build, so a rollback serves the older build again.

Serving

The app answers every path of its host. / and paths that end in / serve that folder's index.html. A path without a file extension tries the file itself, then <path>.html, then <path>/index.html, and finally the root index.html, so client-side routes survive a reload. A missing file with an extension gets the app's 404.html with status 404, or a plain 404 when the app has none.

Browsers keep files whose names carry a content hash, such as assets/index-B3k9x2Qa.js from Vite or anything under _next/static/, for a year. Every other file is revalidated on each request, so a deploy shows up on the next page load. Apps in dev environments aren't cached at all.

An app that the active deployment no longer declares is retired: it stops serving and its visitors are signed out. It keeps its URL, so it comes back on the same address when a later deployment declares it again.

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'self'; base-uri 'self'; form-action 'self'; object-src 'none'

{
  "app": {"key": "portal", "name": "Support portal"},
  "environment": "Production",
  "auth": "oidc",
  "connectors": ["portal-chat"],
  "login_url": "/_connic/login",
  "logout_url": "/_connic/logout"
}

Call agents

An app reaches agents through connectors. List their keys in connectors. Each one must be a sync webhook or a WebSocket connector whose file sets apps_only: true and that is deployed to the same environments as the app. An app with dev needs its connectors in dev environments too, so a connector file with environments needs dev as well.

type: webhook
mode: sync
apps_only: true      # only apps that list this connector can call it
agents:
  - support

The app calls the connector on its own host at /_connic/c/<key>. connic checks the visitor's session first, then forwards the request with the app and the visitor attached. Requests from other sites get 403: a request's Origin must be the app's own, and WebSocket connections must send it. An apps_only connector accepts nothing else: its own URL rejects direct requests, and its secret isn't used. apps_only can only be set in connectors/*.yaml.

const response = await fetch("/_connic/c/portal-chat", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ message: "Where is my order?" }),
});
if (response.status === 401) {
  location.assign(`/_connic/login?return=${encodeURIComponent(location.pathname)}`);
}
const result = await response.json();

A WebSocket connector needs no secret message, so the first message is already a chat message. Its path takes one more segment, a connection ID that the client chooses, as in /_connic/c/portal-chat/<connection id>. Each end user has their own connection IDs. A connection with the ID of an open one replaces it, and answers the visitor missed while disconnected arrive once they reconnect with that ID; see Reconnect. Query strings are passed on. A key the app doesn't list answers 404.

const socket = new WebSocket(`wss://${location.host}/_connic/c/portal-chat`);
socket.onopen = () => socket.send(JSON.stringify({ message: "Where is my order?" }));

context["app"]
# {"id": "0b9c3f1e-5d2a-4e8b-9f1c-7a6d2e4b8c10", "key": "portal"}

context["end_user"]
# {"id": "8d2f6c1a-4b7e-4f0a-9c3d-2e5b7a9f1c64", "email": "ada@example.com",
#  "name": "Ada Lovelace", "groups": ["support"], "signed_in": True}

In the dashboard

The Apps page lists the apps of the selected environment, dev environments included, with their URL, sign-in, and the last 7 days of visitors, views, sign-ins, and data requests. Click an app to open its details:

• Settings: the default URL, the custom domain, sign-in, and the "Powered by connic" line at the end of every page. A setting that the file declares shows an In code badge and can only be changed in code.
• Stats: the last 30 days of visitors, views, sign-ins, data requests, failed sign-ins, denied requests, and connector calls. A view is a page the app served, and a visitor counts once per UTC day.
• Access: the lookups and access rules of the deployed file, read-only.

Seeing apps takes the View apps permission, and changing their settings takes Manage apps, which the default Admin group has. See Team and permissions. connic MCP offers the same with list_apps, get_app, update_app, and get_app_stats.