Deploy and Operate Multica
Multica is an open-source workspace for coordinating AI agents and their work. Edka deploys it as a managed app in your Kubernetes cluster, connects it to a managed PostgreSQL database, and publishes it on a Gateway hostname.
Architecture
Section titled “Architecture”| Component | Purpose | How Edka connects it |
|---|---|---|
| Multica backend | API, WebSocket server, and Prometheus metrics | Installed from the Edka Multica chart |
| Multica frontend | Web application | Installed from the same chart release |
| PostgreSQL | Workspaces, tasks, agent runs, and vector embeddings | Select an installation, database, and user from the Databases workspace |
| Uploads volume | Locally uploaded files | Persistent volume with the selected storage class |
| Envoy Gateway | HTTPS and WebSocket access on one hostname | Select a traffic class and hostname |
Prerequisites
Section titled “Prerequisites”Before installing Multica, prepare:
- an Edka cluster with an Envoy Gateway traffic class and managed TLS
- a DNS hostname for the Multica web application, API, WebSocket, and CLI traffic
- a managed PostgreSQL 17 or 18 installation with a dedicated database and a user that owns it
- the vector (pgvector) extension enabled on that database
Edka validates all three database requirements at install time: the PostgreSQL version, the vector extension on the selected database, and that the selected user owns the selected database. Create the database, owner user, and extension in the Databases workspace first.
For the optional integrations you will also need a Slack app per agent, a GitHub App, a Google OAuth client, or a Resend API key, as described below.
Install Multica
Section titled “Install Multica”- Open your cluster and select Apps.
- Find Multica and select Install.
- In General, choose the namespace and decide whether Edka may automatically apply compatible chart updates.
- In Database, select the PostgreSQL installation, database, and user prepared for Multica. Edka builds the connection string from the selected user’s protected password Secret.
- In Configuration, review authentication and email settings.
- In Integrations, enable Slack, GitHub, or self-hosted Git connections if you want them at install time. You can also enable them later.
- Review storage, resources, placement, and the Gateway hostname.
- Select Install App and follow the operation progress until Multica is ready.
You can install more than one Multica instance per cluster, each with its own namespace, database, and hostname.
Runtime Secrets
Section titled “Runtime Secrets”Multica’s secrets live in a runtime Secret in the app namespace. Edka generates the stable values during installation and preserves them across configuration updates. Leaving an optional secret field empty during an update keeps the current value.
| Secret | Purpose | Handling |
|---|---|---|
| JWT secret | Signs Multica authentication tokens | Generated at install and kept stable; reveal follows the organization’s sensitive-action policy |
| Slack credential encryption key | Encrypts stored Slack bot credentials | Generated when the Slack integration is enabled and preserved afterwards |
| GitHub webhook secret | Validates GitHub webhook deliveries | Supplied by you; at least 16 characters |
| GitHub App private key | Authenticates CI status and mergeability API calls | Supplied by you as a full PEM key |
| Git credential encryption key | Encrypts self-hosted Git credentials | Generated and kept stable automatically |
| Database URL | PostgreSQL connection string | Built from the selected user’s password Secret |
Revealing a stored secret follows your organization’s sensitive-action policy and requires passkey step-up when enforcement is enabled.
Authentication and Email
Section titled “Authentication and Email”The Configuration tab controls who can sign in:
- Allow Sign-up is enabled by default. Disable it to close registration after your team has joined.
- Allowed Emails and Allowed Email Domains restrict registration to a comma-separated allowlist.
- Disable Workspace Creation prevents users from creating new workspaces after initial setup.
- Google OAuth adds Google as a sign-in provider. Supply the client ID and
secret, and configure the OAuth client’s authorized redirect URI as
https://<your-hostname>/auth/callback. - Sender Email and an optional Resend API Key enable transactional email such as invitations.
Slack Integration
Section titled “Slack Integration”Enable Slack Bots in the Integrations tab. Edka generates the key that encrypts stored Slack credentials and keeps it stable across updates.
After installation, workspace admins connect one Slack Socket Mode app per Multica agent from inside Multica. Follow the upstream Slack setup guide to create the Slack apps.
GitHub Integration
Section titled “GitHub Integration”The GitHub integration connects a GitHub App for pull request linking and merge-to-Done automation.
- Create a GitHub App following the upstream GitHub setup guide.
- Enable GitHub in the Integrations tab.
- Enter the GitHub App Slug from the App URL, for example
multica-acme. The slug uses lowercase letters, numbers, and hyphens. - Enter the GitHub Webhook Secret configured on the App. This is the webhook secret, not the OAuth client secret.
- After installation, open the app endpoints and copy the GitHub App Setup URL and GitHub Webhook URL into the GitHub App settings. Enable Redirect on update for the setup URL.
To show CI status and mergeability on PR cards and enable the repository picker, also enable GitHub CI and Mergeability and provide the numeric GitHub App ID and the GitHub App Private Key as a full PEM key, including the BEGIN and END lines and line breaks.
Self-Hosted Git
Section titled “Self-Hosted Git”Enable Self-hosted Git to allow Forgejo, Gitea, and GitLab connections from inside Multica. Edka generates the credential encryption key automatically and keeps it stable.
Gateway Hostname and Endpoints
Section titled “Gateway Hostname and Endpoints”Multica always publishes through an Envoy Gateway traffic class. One hostname carries the web application, the API, WebSocket connections, and the Multica CLI. After installation, Edka shows:
- the external HTTPS URL
- internal service URLs for the web and API endpoints
- the PostgreSQL connection endpoint
- the GitHub setup and webhook URLs when the GitHub integration is enabled
- an internal Prometheus endpoint on port
9090
Storage, Resources, and Placement
Section titled “Storage, Resources, and Placement”| Option | Default | Notes |
|---|---|---|
| Uploads volume | 10Gi | Persistent volume for locally uploaded files |
| Storage class | hcloud-volumes | Fixed at install time |
| Backend | 100m CPU, 256Mi requested | Optional CPU and memory limits |
| Frontend | 100m CPU, 256Mi requested | Optional CPU and memory limits |
Both deployments run without limits by default, which keeps them in the Burstable QoS class. Set explicit limits when you want a ceiling. You can also place Multica on a selected node pool and automatically tolerate that pool’s taints.
Metrics
Section titled “Metrics”The backend publishes Prometheus metrics at :9090/metrics. When the cluster
metrics backend is available, Edka’s app view surfaces:
- HTTP request rate, p95 latency, and active requests
- agent tasks enqueued, failed, and in progress
- LLM tokens and estimated LLM cost in USD
See Cluster Metrics for the metrics backend setup.
Updates
Section titled “Updates”Chart auto-updates are opt-in. You can allow patch, minor, major, all, or a custom version pattern and choose how often Edka checks. Updates preserve the runtime secrets, so agent credentials and sign-in sessions survive chart upgrades.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| PostgreSQL version is rejected | Multica requires a managed PostgreSQL 17 or 18 installation |
| The selected user must own the database | Pick the database’s owner user, or change the owner in the Databases workspace |
| The vector extension is required | Enable the vector extension on the selected database in the Databases workspace |
| GitHub App slug is rejected | Use the slug from the App URL: lowercase letters, numbers, and hyphens, not the display name |
| GitHub App ID is rejected | Enter the numeric App ID from the GitHub App settings page |
| GitHub App private key is rejected | Paste the full PEM key including the BEGIN and END lines and line breaks |
| Webhook deliveries fail | Copy the webhook URL from the app endpoints and confirm the secret matches the App’s webhook secret |
| Google sign-in fails | Set the OAuth client’s authorized redirect URI to https://<your-hostname>/auth/callback |
| Backend stays unready | Verify database connectivity and review the backend Logs for startup errors |