Build your first Caraer app

Create a local app project, test a function, and deploy it to a sandbox company. Apps are authored with the CLI. The Caraer UI installs and configures them.

Before you begin

Use Python 3.10 or newer and a sandbox company. A private app requires the company app-write permission. Public marketplace apps require a Developer or Super admin role and marketplace review before other companies can install them.

pipx install caraer-cli
caraer --version
caraer auth login
caraer company list
caraer company select <company-uuid>

Scaffold a private app

caraer apps init --private --name hello_inbox --label "Hello Inbox" --auth-method NONE
cd hello_inbox

The project contains caraer.json, src/app/app.caraer.yaml, a sample function, and lifecycle hooks. Keep privateApp: true for a company-only app. Omit --private when deliberately creating a public marketplace app.

Write a function

Use the scaffolded function’s handler shape. A Node handler can return a simple result:

export const handler = async (req, res) => {
  const body = req.body || {};
  return res.status(200).json({ ok: true, event: body.event || null });
};

For Caraer API calls, use the injected caraerApiBase and short-lived installationToken from the invocation envelope. See functions for the payload and local test flow.

Validate and run locally

caraer apps validate
caraer apps local dev

In another terminal, use the scaffold’s actual function name:

curl -X POST 'http://127.0.0.1:8787/functions/<function-name>' \
  -H 'Content-Type: application/json' \
  -d '{"event":"demo"}'

Inspect the handler response and logs. A local request proves the handler can process that input; it does not establish that production webhooks are delivered.

Push and verify

caraer apps push --dry-run
caraer apps push --deploy
caraer apps status

In Caraer, open Private apps (or App store for a public app) and check the card’s Installed or Not installed label. The Installed apps tab filters that public or private listing while keeping category, subcategory, and search filters. Switching tabs returns to page one.

Confirm the runtime is ready, then exercise the installed app’s actual trigger. For public apps, complete listing fields and follow caraer publish submit.

Add the next capability

Common mistakes

Using a customer tenant for development, hardcoding platform URLs, or treating an installation token as a permanent API key makes integrations fragile. Use the scaffold, declared permissions, and runtime context. The CLI reference and API reference describe the complete interfaces.