diff --git a/docs-site/concepts/connectors.mdx b/docs-site/concepts/connectors.mdx index 074ef9389d..cabcced5c0 100644 --- a/docs-site/concepts/connectors.mdx +++ b/docs-site/concepts/connectors.mdx @@ -1,62 +1,31 @@ --- -title: Connectors and Grants -description: Bring external services into a pod with explicit install and tool access. +title: Connectors +description: Channels and tools for your pods --- -A connector brings an external service into Commonly. Its installable entry -describes the capability; its installation chooses the target scope; its -credentials and grants decide what can actually be used. +Open **Connectors** in Commonly. Channels carry messages between a pod and an +outside chat. Tools let an agent read or act in another service after the +connection owner grants access. -## Three records, three jobs +This live Connectors page shows a free account before any connection or tool +grant. Slack and Telegram are under **Channels**; GitHub and Linear are under +**Tools**. Other tools visible in the list are outside the walked guides here. -| Record | Job | -|---|---| -| Installable | Catalog metadata, components, required capabilities, and version. | -| Credential | Secret material and credential lineage, kept separate from the connector record. | -| Grant | Server-enforced permission connecting a caller, tool, connector, and audience. | - -Keeping these records separate means installing a connector does not silently -grant every tool or expose the underlying secret to a pod. - -## Catalog and installation - -Authenticated users can inspect the connector catalog: - -~~~http -GET /api/installables -~~~ - -An installation is created from the shell or the installable lifecycle route. -The connector is then projected into its target scope, such as a user or pod. -The exact lifecycle depends on the connector; use the app's install flow for -OAuth-backed services. - -## Grants +
+ Desktop Connectors page before setup, with Slack and Telegram channels above the tools list +
-Grants are explicit server records. The API exposes the pod's grants and -individual grant details: +
+ Mobile Connectors page before setup, with Add on Slack and Telegram and Connect on Linear +
-~~~http -GET /api/pods/:podId/grants -GET /api/grants/:grantId -GET /api/grants/:grantId/calls -~~~ - -Connector tools should be called through the grant that authorized them. A -grant can be revoked, and revocation cascades to the calls that depend on it. - -## Credentials - -Credential metadata is owner-scoped: - -~~~http -GET /api/credentials -DELETE /api/credentials/:id -~~~ - -The API never uses a pod message as a credential store. Keep secret values in -the deployment's secret manager and grant only the connector operations the -target agent or pod needs. - -See [Marketplace](/marketplace/overview) for the installable catalog and -[Agent Tools](/agents/tools) for the runtime-facing tool surface. +| Connector | Current path | +|---|---| +| [Telegram](/integrations/telegram) | Bind a private chat and choose which pods reach it. | +| [Slack](/integrations/slack) | Authorize a workspace, then confirm the connection. | +| [GitHub App](/integrations/github) | An instance administrator installs the app; the connection owner grants tools. On commonly.me this is limited to the instance's own repository. | +| [Linear](/integrations/linear) | Connect your account and grant read access to an eligible pod. | + +The page also lists connectors that are unavailable on this instance. A listed +row is not a working connection. The [grants guide](/concepts/grants) explains +how a connection owner limits tool access and revokes it. diff --git a/docs-site/concepts/grants.mdx b/docs-site/concepts/grants.mdx index a6f5dac40b..5c8a863e0e 100644 --- a/docs-site/concepts/grants.mdx +++ b/docs-site/concepts/grants.mdx @@ -17,9 +17,10 @@ secret, and revoking it does not replace the credentials held by the connector. 5. The broker checks the grant before each tool call and records the outcome. 6. The connection owner can revoke a grant; revocation cascades to its children. -The current root-grant route accepts connected GitHub App installations. The -server derives the installation and broker from the connection, rather than -trusting those values from the request body. +The root-grant route accepts connected GitHub App installations and supported +hosted MCP connections, including Linear. Linear grants are read-only and work +only in eligible private pods. The server derives the installation and broker +from the connection, rather than trusting those values from the request body. ## Targets and audience diff --git a/docs-site/deployment/docker.mdx b/docs-site/deployment/docker.mdx index 53a04caa46..2482bc920b 100644 --- a/docs-site/deployment/docker.mdx +++ b/docs-site/deployment/docker.mdx @@ -1,88 +1,26 @@ --- -title: Docker Compose (local) -description: Run Commonly on one local machine with Docker Compose. +title: Docker Compose +description: Local operation and data retention --- -This is the supported Docker Compose path for trying Commonly locally or on a -private single machine. It is not a public-domain production deployment. +Start with [Self-host Commonly](/deployment/index). The local Compose profile +builds the frontend, backend, and MongoDB on one machine. It does not include +TLS, a reverse proxy, public-domain configuration, or PostgreSQL. -## Prerequisites - -- [Docker Engine](https://docs.docker.com/get-docker/) with the Compose v2 plugin -- Git -- Ports `3000` and `5000` free on the Docker host - -## Start Commonly - -```bash -git clone https://github.com/Team-Commonly/commonly.git -cd commonly -./install.sh -``` - -The installer writes an ignored `.env` file containing a generated `JWT_SECRET` -when one is missing, then builds and starts the services. Keep that file for -future Compose commands: changing the secret invalidates existing sessions. - -Open **http://localhost:3000** and verify the backend: +From the repository root, check the API after `./install.sh`: ```bash curl --fail --silent http://localhost:5000/api/health ``` -## What this profile includes - -| Service | Port | Notes | -|---|---:|---| -| frontend | 3000 | Static React app | -| backend | 5000 | Node.js API | -| mongo | internal only | Persistent `mongo-data` Docker volume | - -The profile deliberately does not include PostgreSQL, TLS, a reverse proxy, or -public-domain configuration. PostgreSQL-specific features, including threaded -agent messages, are not enabled. Do not expose these ports directly to the -internet. - -## Operate and update +The installer keeps configuration in an ignored `.env` file. Use that file +when checking status or stopping the stack: ```bash -# Status and logs docker compose --env-file .env -f docker-compose.local.yml ps -docker compose --env-file .env -f docker-compose.local.yml logs -f - -# Stop containers and retain data docker compose --env-file .env -f docker-compose.local.yml down - -# Update the checkout and rebuild -git pull --ff-only -docker compose --env-file .env -f docker-compose.local.yml up -d --build -``` - - -`docker compose --env-file .env -f docker-compose.local.yml down -v` removes -the MongoDB volume and its data. Use it only when you intend to reset the local -installation. - - -## Configure a local install - -Add optional settings to the ignored root `.env` file, then restart the stack. -For a shared private machine, you can restrict registration: - -```dotenv -REGISTRATION_INVITE_ONLY=true -REGISTRATION_INVITE_CODES=replace-with-private-codes ``` -Leave integration credentials unset unless you are using that integration, and -never commit `.env`. - -## Development and public deployment - -Use `./dev.sh up` for contributor development with source mounts and hot reload. -It is a different profile from the local install above. - -For a public deployment, configure TLS, ingress or a reverse proxy, a -non-local frontend API URL, backups, and deployment-specific secrets. Start -with the [Kubernetes / Helm guide](/deployment/kubernetes); do not promote the -local Compose profile by exposing its ports. +The `down` command keeps the MongoDB volume. Adding `-v` removes the volume +and its data. For logs, updates, and optional settings, follow the +[repository's local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md). diff --git a/docs-site/deployment/environment-variables.mdx b/docs-site/deployment/environment-variables.mdx index 58be822913..b414a65ae5 100644 --- a/docs-site/deployment/environment-variables.mdx +++ b/docs-site/deployment/environment-variables.mdx @@ -1,73 +1,15 @@ --- -title: Environment Variables -description: Environment variables for local and self-hosted Commonly deployments. +title: Environment variables +description: Configuration sources for self-hosting --- -Start from .env.example for the full template. The values below are the -application variables most deployments need; provider and integration -credentials are optional unless the related feature is enabled. +The local installer creates an ignored `.env` with a generated `JWT_SECRET` +when one is missing. Keep it private and keep the value stable so existing +sessions continue to work. -## Database - -| Variable | Description | -|---|---| -| MONGO_URI | MongoDB connection string. | -| PG_HOST | PostgreSQL host for the message store. | -| PG_PORT | PostgreSQL port; defaults to 5432. | -| PG_DATABASE | PostgreSQL database name. | -| PG_USER | PostgreSQL user. | -| PG_PASSWORD | PostgreSQL password. | -| PG_SSL_ENABLED | Enable PostgreSQL TLS. | -| PG_SSL_CA_PATH | CA certificate path when PostgreSQL TLS requires one. | - -If PG_HOST is unset, the application falls back to MongoDB for the local -development path. The Docker Compose services can use their internal service -names instead of localhost. - -## Authentication and server - -| Variable | Description | Local example | -|---|---|---| -| JWT_SECRET | Secret used to sign human-session JWTs. Use a random value in production. | openssl rand -hex 32 | -| PORT | Backend listen port. | 5000 | -| NODE_ENV | Application environment. | development | -| FRONTEND_URL | Browser origin allowed by the backend. | http://localhost:3000 | -| BACKEND_URL | Backend origin used by local tooling. | http://localhost:5000 | - -Changing JWT_SECRET invalidates existing human sessions. - -## Model providers - -| Variable | Description | -|---|---| -| ANTHROPIC_API_KEY | Credentials for Claude API calls. | -| OPENAI_API_KEY | Credentials for OpenAI-compatible calls. | -| OPENAI_BASE_URL | Optional OpenAI-compatible API origin. | -| OPENROUTER_API_KEY | Credentials for OpenRouter fallback routing. | -| OPENROUTER_BASE_URL | Optional OpenRouter-compatible API origin. | -| GEMINI_API_KEY | Credentials for backend services that use Gemini. | -| LITELLM_API_KEY | Virtual key for a LiteLLM proxy. | -| LITELLM_BASE_URL | LiteLLM proxy origin. | -| LITELLM_MASTER_KEY | Operator key for LiteLLM administration. | - -Provider variables are only needed when the enabled runtime or feature uses -that provider. GEMINI_API_KEY remains a supported backend input; it should not -be treated as an API reference or as a replacement for the runtime token. - -## Agent and integration features - -| Variable | Description | -|---|---| -| BRAVE_API_KEY | Brave Search access for agents that use search. | -| TAVILY_API_KEY | Tavily access for agents that use search. | -| FIRECRAWL_API_KEY | Firecrawl access for agents that use crawling. | -| DEEPGRAM_API_KEY | Speech or transcription provider credentials. | -| GITHUB_PAT | GitHub access for configured development workflows. | -| DISCORD_CLIENT_ID | Discord OAuth application ID. | -| DISCORD_CLIENT_SECRET | Discord OAuth application secret. | -| DISCORD_BOT_TOKEN | Discord bot credential. | -| DISCORD_PUBLIC_KEY | Discord interaction signature key. | -| TELEGRAM_BOT_TOKEN | Telegram bot token. | - -Never commit these values or put them in pod memory. Use deployment secrets for -production and grant each feature only the credentials it needs. +The local profile forwards only the variables listed in +[`docker-compose.local.yml`](https://github.com/Team-Commonly/commonly/blob/main/docker-compose.local.yml). +The repository's [`.env.example`](https://github.com/Team-Commonly/commonly/blob/main/.env.example) +covers broader development and deployment settings; putting a variable in +`.env` does not make the local Compose profile forward it. For connector setup, +follow its guide and the [self-hosting guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md). diff --git a/docs-site/deployment/index.mdx b/docs-site/deployment/index.mdx new file mode 100644 index 0000000000..9f265193a1 --- /dev/null +++ b/docs-site/deployment/index.mdx @@ -0,0 +1,35 @@ +--- +title: Self-host Commonly +description: Local setup with Docker Compose +--- + +## Before you start + +You need Git, Docker Engine with the Compose v2 plugin, OpenSSL if the installer +must create `.env`, and free ports `3000` and `5000`. Check Docker with +`docker compose version`. + +## Start + +Run the same three steps shown on the Commonly home page: + +```bash +git clone https://github.com/Team-Commonly/commonly.git +cd commonly +./install.sh +``` + +Open [http://localhost:3000](http://localhost:3000). The installer builds and +starts the local frontend, backend, and MongoDB. It creates an ignored `.env` +file with a generated `JWT_SECRET` if you do not already have one. Keep that +file; changing the secret signs everyone out. + +This Compose setup is for one local or private machine. It has no TLS, reverse +proxy, or public-domain configuration. Keep its ports off the public internet. + +For health checks, updates, and data retention, follow the +[local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md). +For a public deployment, read the +[Kubernetes guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/KUBERNETES.md) +and [Helm values reference](https://github.com/Team-Commonly/commonly/blob/main/docs/self-hosting/helm-reference.md) +before choosing an environment. diff --git a/docs-site/deployment/kubernetes.mdx b/docs-site/deployment/kubernetes.mdx index fe420241c8..a43c071db5 100644 --- a/docs-site/deployment/kubernetes.mdx +++ b/docs-site/deployment/kubernetes.mdx @@ -1,128 +1,14 @@ --- -title: Kubernetes / Helm -description: Configure and deploy Commonly to Kubernetes with the included Helm chart. +title: Kubernetes +description: Planning a public deployment --- -The Helm chart is the advanced path for a public Commonly deployment on GKE, -EKS, AKS, or local kind. You must supply your own container registry, secrets, -ingress configuration, and database plan before installing it. +The three-step install on [Self-host Commonly](/deployment/index) is a local +Compose setup. It does not supply the TLS, ingress, database, secrets, and +backup plan needed for a public deployment. -## Prerequisites - -- Helm 3+ -- A Kubernetes cluster -- MongoDB and PostgreSQL (managed or self-hosted) - -## Install with Helm - -```bash -helm install commonly k8s/helm/commonly \ - -n commonly \ - --create-namespace \ - -f k8s/helm/commonly/values.yaml \ - -f k8s/helm/commonly/values-local.yaml -``` - - -Always pass `-f values.yaml -f values-override.yaml` explicitly. Never use `--reuse-values` — stale stored values will override your current config silently. - - -## Values files - -| File | Purpose | -|---|---| -| `values.yaml` | Base defaults — project refs, PG host/port, feature flags | -| `values-dev.yaml` | GKE dev overrides — image tags, ingress hosts, node selectors | -| `values-local.yaml` | Local kind setup — in-cluster MongoDB + PostgreSQL, no cloud deps | - -For a self-hosted OSS install, start with `values-local.yaml`: - -```bash -helm install commonly k8s/helm/commonly \ - -f k8s/helm/commonly/values.yaml \ - -f k8s/helm/commonly/values-local.yaml -``` - -## Key values - -```yaml -backend: - image: - repository: gcr.io/your-project/commonly-backend - tag: "latest" - env: - JWT_SECRET: "change-me" - MONGO_URI: "mongodb://mongo:27017/commonly" - -frontend: - image: - repository: gcr.io/your-project/commonly-frontend - tag: "latest" - -ingress: - enabled: true - hosts: - - host: app.yourdomain.com - paths: ["/"] - - host: api.yourdomain.com - paths: ["/"] -``` - -## Building images - -```bash -# Backend -docker build -t your-registry/commonly-backend:latest backend/ -docker push your-registry/commonly-backend:latest - -# Frontend (requires REACT_APP_API_URL at build time) -docker build \ - --build-arg REACT_APP_API_URL=https://api.yourdomain.com \ - -t your-registry/commonly-frontend:latest \ - frontend/ -docker push your-registry/commonly-frontend:latest -``` - -## Upgrading - -```bash -helm upgrade commonly k8s/helm/commonly \ - -n commonly \ - -f k8s/helm/commonly/values.yaml \ - -f k8s/helm/commonly/values-local.yaml -``` - -## Check status - -```bash -kubectl get pods -n commonly -kubectl logs -n commonly -l app=backend -kubectl logs -n commonly -l app=frontend -``` - -## Local kind cluster - -For local Kubernetes testing without a cloud account: - -```bash -./dev.sh cluster up # spin up kind cluster + install commonly -./dev.sh cluster test # run integration tests against it -./dev.sh cluster down # tear down -``` - -## Production preflight - -Before exposing a deployment, verify each item against the environment that -will run it: - -Change `JWT_SECRET` from the default value -Do not expose the local Compose ports directly to the internet -Set `MONGO_URI` to a production MongoDB with authentication enabled -Set `FRONTEND_URL` to the actual frontend domain -Build the frontend with the production API URL -Enable TLS on both frontend and backend ingress -Set up MongoDB backups -Set up PostgreSQL backups when PostgreSQL is configured -Configure `AGENT_SESSION_MAX_SIZE_KB` -Test runtime-token authentication end to end -Seed an initial admin user and at least one pod +For a Kubernetes deployment, use the repository's +[deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/KUBERNETES.md) +and [Helm values reference](https://github.com/Team-Commonly/commonly/blob/main/docs/self-hosting/helm-reference.md). +Choose image, database, secrets, ingress, and backup settings for your own +cluster before running Helm. diff --git a/docs-site/docs.json b/docs-site/docs.json index f8fa8d4f8e..ae6c0740de 100644 --- a/docs-site/docs.json +++ b/docs-site/docs.json @@ -64,7 +64,11 @@ "group": "Connectors", "pages": [ "concepts/connectors", - "concepts/grants" + "concepts/grants", + "integrations/telegram", + "integrations/slack", + "integrations/github", + "integrations/linear" ] }, { @@ -80,8 +84,9 @@ ] }, { - "group": "Self-Hosting", + "group": "Self-host", "pages": [ + "deployment/index", "deployment/docker", "deployment/kubernetes", "deployment/environment-variables" @@ -94,14 +99,6 @@ "marketplace/manifest", "marketplace/publishing" ] - }, - { - "group": "Integrations", - "pages": [ - "integrations/github", - "integrations/linear", - "integrations/discord" - ] } ] }, diff --git a/docs-site/images/connectors-desktop.png b/docs-site/images/connectors-desktop.png new file mode 100644 index 0000000000..1b1808d036 Binary files /dev/null and b/docs-site/images/connectors-desktop.png differ diff --git a/docs-site/images/connectors-mobile.png b/docs-site/images/connectors-mobile.png new file mode 100644 index 0000000000..046b60830d Binary files /dev/null and b/docs-site/images/connectors-mobile.png differ diff --git a/docs-site/integrations/discord.mdx b/docs-site/integrations/discord.mdx index 45b060d00b..86aecd98ad 100644 --- a/docs-site/integrations/discord.mdx +++ b/docs-site/integrations/discord.mdx @@ -1,38 +1,8 @@ --- -title: Discord Integration -description: Sync Discord channels with Commonly pods. +title: Discord availability +description: Availability on commonly.me --- -Commonly can automatically pull messages from Discord channels into pod summaries, and post pod activity back to Discord. - -## Setup - -1. Create a Discord application at [discord.com/developers](https://discord.com/developers/applications) -2. Add a bot with `Read Messages`, `Send Messages`, `Read Message History` permissions -3. Set environment variables: - -```bash -DISCORD_BOT_TOKEN=... -DISCORD_CLIENT_ID=... -DISCORD_CLIENT_SECRET=... -``` - -4. Link a Discord channel to a pod in **Pod Settings → Integrations → Discord** - -## Slash commands - -After deploying: `npm run discord:deploy` to register commands. - -| Command | Description | -|---|---| -| `/commonly-summary` | Show latest pod summary in Discord | -| `/discord-push` | Manual sync: pull last hour's Discord messages into pod | -| `/discord-enable` | Enable automatic hourly sync | -| `/discord-disable` | Disable automatic hourly sync | -| `/discord-status` | Show current integration status | - -## Automatic sync - -When enabled, Commonly fetches messages from the linked Discord channel every hour, generates an AI summary, and posts it to the pod as `@commonly-bot`. - -The sync filters out bot messages, empty content, and applies time-range filtering. +Discord appears in the connector catalog as **Not enabled on this instance**. +It is not offered for connection on commonly.me, so there are no working +connection steps to follow here. Ask your instance operator about availability. diff --git a/docs-site/integrations/github.mdx b/docs-site/integrations/github.mdx index 790aef0114..916be9b39b 100644 --- a/docs-site/integrations/github.mdx +++ b/docs-site/integrations/github.mdx @@ -1,48 +1,35 @@ --- -title: GitHub Integration -description: GitHub issue access for Commonly integrations and agents. +title: GitHub App +description: Scoped access to the connected repository --- -GitHub access is a standalone integration. The task board does not create, -import, comment on, or close GitHub Issues. +On commonly.me, the GitHub App is installed for the instance's own repository. +An individual team cannot connect its own repository through this flow yet. +The task board does not create or close GitHub issues by itself. -## Setup +## Grant access -Provide a GitHub Personal Access Token (PAT) with `Issues` and `Pull requests` read/write permissions: +The instance administrator manages the app installation. A non-admin sees the +installation requirement in **Connectors → Tools**, but cannot install the app. +For an existing connection: -```bash -GITHUB_PAT=ghp_... -``` +1. The connection owner selects **Add** on the GitHub row, chooses the pod, + agents, access mode, and end date, then selects **Grant**. +2. Open the grant to inspect calls, change access, or revoke it. -Or configure via **Global Integrations → GitHub** in the admin UI. +The grant requires a private, unbridged pod with agents running in Commonly's +narrowed in-process runtime. If the pod is joinable, the grant flow can ask its +owner to make it invite-only before continuing. -## How it works +The live desktop view shows the GitHub row before installation or a grant. It +names the instance's own repository and tells a non-admin that an administrator +must install the app first. -Use the GitHub API endpoints or agent tools directly when a workflow needs an -issue action. An event handler can connect that action to another surface when -the integration is explicitly installed and configured for it. +
+ GitHub tool row on the desktop Connectors page, before the app is installed or access granted +
-## API endpoints - -```bash -# List open GitHub issues -GET /api/github/issues?owner=Team-Commonly&repo=commonly - -# Create a GitHub issue -POST /api/github/issues -{ "title": "...", "body": "...", "labels": ["backend"] } - -# Add comment to issue -POST /api/github/issues/:number/comment -{ "body": "..." } - -# Close issue -POST /api/github/issues/:number/close -``` - -## Agent tools - -``` -commonly_list_github_issues(owner, repo, { state: "open" }) -commonly_create_github_issue(owner, repo, title, body, labels) -``` +The recorded grant named `list_issues`, `create_issue`, and `close_issue` for +the instance's repository, with confirmation before writes. The readiness +matrix has not recorded an agent completing those actions on the current +build. Access is limited to the grant's audience and expires at its end date. diff --git a/docs-site/integrations/linear.mdx b/docs-site/integrations/linear.mdx index eea286062d..6392450a65 100644 --- a/docs-site/integrations/linear.mdx +++ b/docs-site/integrations/linear.mdx @@ -1,83 +1,50 @@ --- title: Linear -description: Let agents in a pod read your Linear issues, projects and cycles. Read-only. +description: Read access to your Linear workspace --- -The Linear connector lets the agents you choose read your Linear workspace: -issues, projects, cycles, documents, comments, releases and teams. It is -**read-only**. Commonly asks Linear for read access plus your identity -(`read openid`) and nothing more, and refuses to save a connection if Linear -grants more than it asked for. An agent -can't create, edit, comment on or close anything in Linear. +Linear gives a granted agent read access to issues, projects, cycles, and +teams. It cannot create or edit Linear content. Commonly requests only +`read openid` from Linear. ## What agents can read | Area | Examples | |---|---| -| Issues | list and open issues, their statuses, labels and comments | -| Projects and cycles | projects, project labels, milestones, cycles, status updates | -| Documents | workspace documents and templates | -| Releases | release pipelines, releases and release notes | -| People and teams | teams, members, the workspace itself, triage responsibility | -| Agent features | Linear Agent skills, custom views, notifications, diffs and their threads | - -Two Linear tools are deliberately left out. Both can make Linear fetch a URL the -caller chooses: reading an attachment, and extracting the images from a -document. - -## Connect your Linear account - -1. Open **Connectors** and find **Linear** in the tools list. -2. Click **Connect**. Linear opens and asks you to approve **Commonly (Linear)** - with **Read** and **Identity** access. -3. Pick the Linear workspace to connect, and approve. Linear sends you back to - Connectors. - -The connection belongs to you. Nobody else can use it, and no agent can use it, -until you grant it to a pod. - -## Grant it to a pod - -1. On the Linear row, click **Add**. -2. If you're in more than one pod, choose the pod. -3. Under **agents**, tick the agents that may use it. -4. Under **ends**, choose when access ends: in 7, 30 or 90 days. -5. Click **Grant**. - -Then ask one of those agents in the pod, for example -`@Scout what's in progress for the PAY team?`. Every call the agent makes is -recorded against the grant, and you can see the calls in the grant's details on -the Connectors page. - -Linear content can carry instructions written by anyone in your workspace, so -Commonly gives agents everything that comes from Linear marked as untrusted -data, not instructions. - -### Which pods can hold a Linear grant - -Linear issues can be written by people outside your team, so a Linear grant is -accepted only in a pod that keeps its contents in: - -- **private**: not readable by the public; -- **invite-only**: people can't join by themselves; -- **not bridged**: not relayed to Discord, Slack or another outside channel; -- **only Commonly's built-in agents**: every agent in the pod is one of - Commonly's own, such as Scout. An agent you brought yourself doesn't qualify, - whether it runs on your computer, on another service, or on Commonly through - **Run it here** on the Bring your own agent page. - -A new **My Workspace** meets all four: it starts private and invite-only, with -Scout as its only agent. It keeps qualifying only while that stays true. The -check reads the pod as it is now, not its name, so if you open it to anyone, -bridge it to a channel, or add an agent you brought yourself, its Linear grants -stop working at the next call. - -## Stop access - -**Stop an agent using Linear:** on the Connectors page, open the Linear grant, -click **Revoke**, then **Yes, revoke it**. It takes effect at the agent's next -call. A grant also ends on its own on the date you chose. - -**Remove Commonly from your Linear account:** in Linear, open **Settings → -Security & access**. Under **Authorized applications**, the connection is listed -as **MCP** with **Read** access. Click **Revoke**. +| Issues | List and open issues, statuses, labels, and comments | +| Projects and cycles | Projects, labels, milestones, cycles, and status updates | +| Documents | Workspace documents and templates | +| Releases | Release pipelines, releases, and release notes | +| People and teams | Teams, members, the workspace, and triage responsibility | +| Agent features | Linear Agent skills, custom views, notifications, diffs, and their threads | + +Two Linear tools are deliberately withheld: reading an attachment and +extracting a document's images. Both can make Linear fetch a URL chosen by the +caller. + +## Connect and grant + +1. Open **Connectors → Tools** and select **Connect** on Linear. +2. In Linear, choose your workspace and approve **Read** and **Identity**. +3. Back in Commonly, select **Add** on Linear. Choose an eligible pod and the + agents that may use it, set when access ends, then select **Grant**. +4. Ask an agent in that pod to read something from Linear, such as its teams. + Open the grant to see the call trail. + +The live desktop view shows **Connect** on Linear before account authorization. +The grant controls appear after the account is connected. + +
+ Linear Connect button on the desktop Connectors page before account authorization or a pod grant +
+ +The recorded walk used a private, invite-only **My Workspace** with no bridge +and Scout as its only agent. A pod must keep those conditions for the Linear +grant to work. Every agent in it must run in Commonly's narrowed in-process +runtime. An agent you added can qualify if it uses that runtime; an agent +running on your computer or another service does not. + +To stop access, open the grant and select **Revoke**, then **Yes, revoke it**. +To withdraw the Linear connection itself, open **Settings → Security & access** +in Linear and revoke **MCP** under **Authorized applications**. Linear content +is passed to agents as untrusted data, not instructions. diff --git a/docs-site/integrations/slack.mdx b/docs-site/integrations/slack.mdx new file mode 100644 index 0000000000..7f6e596465 --- /dev/null +++ b/docs-site/integrations/slack.mdx @@ -0,0 +1,27 @@ +--- +title: Slack +description: Pod messages in a Slack direct message +--- + +## Connect + +1. Open **Connectors** and choose **Add** on Slack. +2. Choose a pod under **Pod to bridge**, then select **Connect**. +3. Select **Authorize in Slack**, approve Commonly in Slack, and return to + Commonly. +4. Check the workspace and Slack user shown, then select **Confirm connection**. + +The live mobile view shows **Add** on Slack before authorization. The connected +state appears after confirmation. + +
+ Slack Add button on the mobile Connectors page before authorization +
+ +With an agent in the pod, its messages can reach a Slack direct message. A +message that mentions the agent there can enter the pod, and its answer can +return to Slack. The relay identifies the pod and agent. + +If you operate the Slack app for a self-hosted instance, enable the App Home +messages tab and verify the Events Request URL in Slack's app settings so +direct messages can reach Commonly. diff --git a/docs-site/integrations/telegram.mdx b/docs-site/integrations/telegram.mdx new file mode 100644 index 0000000000..e471be6f8e --- /dev/null +++ b/docs-site/integrations/telegram.mdx @@ -0,0 +1,28 @@ +--- +title: Telegram +description: A private chat linked to your pods +--- + +## Connect + +1. Open **Connectors** and choose **Add** on Telegram. +2. Choose a pod under **Pod to bridge**, then select **Connect**. +3. Open a private chat with the Commonly bot. Copy the complete + `/commonly-enable` command shown in Commonly and send it to the bot. The + code expires after 10 minutes; use **New code** if needed. + +The live mobile view shows **Add** on Telegram before setup. The code and pod +switches appear later in the flow. + +
+ Telegram Add button on the mobile Connectors page before setup +
+ +Under **Pods that reach this channel**, switch on each pod whose agent messages +should go to this chat. That includes the active pod when its switch is on. +Messages you send from Telegram enter only the active pod. The line in +Commonly names its Telegram sender. + +One private chat binds to one Commonly user. To move it to another account, +remove the existing binding first. If the chat stops accepting messages, +Commonly shows a named failure on the connector row. diff --git a/docs-site/introduction.mdx b/docs-site/introduction.mdx index be357837cc..3a9fb478fe 100644 --- a/docs-site/introduction.mdx +++ b/docs-site/introduction.mdx @@ -24,7 +24,7 @@ without depending on any one runtime. First-class members with a portable identity, runtime token, and memory. - + Bring external services into a pod through an installable connector and its grants. @@ -54,7 +54,7 @@ request a seat for the daemon. The listener makes it answer @mentions; the MCP server gives it Commonly's tools. - + Start the local Docker profile on your own machine.