Skip to content
Docs menu

Slack, Linear and Jira

Connect your own Slack app so the team can ask venom in channels and DMs, and hand Linear or Jira issues to venom so a runner you control opens a pull request for each, all through Venom Cloud's Integrations page.

View .md

Venom Cloud can work where your team already does. Each integration is your own app: you create it in your own workspace and paste its credentials into the console. Venom registers nothing on any account, and nothing is sent to Slack, Linear, Jira or anywhere else until an admin connects it. Credentials are sealed in the cloud's vault like provider keys, so a self-hosted cloud needs VENOM_VAULT_KEYS set.

In the console, Integrations in the sidebar (/integrations). Reading needs org:read; connecting, changing and disconnecting need org:manage.

Slack

Mention @venom in a channel, send it a direct message, or use /venom <question>. It answers in the thread with one of your org's gears, streams the answer into the message as it arrives, and ends with a context line: the gear, the model, what the answer cost, the tokens, and whose budget it counted toward.

Set up

  1. Integrations → Slack → Connect Slack. The page shows an app manifest with your cloud's URLs in it.
  2. In Slack, api.slack.com/apps → Create New App → From an app manifest, pick your workspace, choose JSON and paste the manifest. It asks for these bot scopes only: app_mentions:read, chat:write, commands, im:history, channels:history, groups:history.
  3. Install to Workspace, then paste two values into the console and click Save and check: the Signing secret (Basic Information → App Credentials) and the Bot User OAuth Token (xoxb-…, OAuth & Permissions). The token is checked with Slack once, then sealed. Neither is shown again; the page shows their last four characters.
  4. In the app's Event Subscriptions, click Retry next to the request URL. The console's third step turns green when Slack's first request arrives.
  5. Invite the bot to a channel (/invite @venom) and mention it.

How it answers

Setting What it does Default
Channel gears A gear per channel, set on the Slack page or with /venom gear <name> in the channel by an owner or admin who linked their Slack user (/venom gear default clears it). the integration's default gear, else the org's
Who pays A member runs /venom link in Slack and confirms in the console; their answers then use a key of their own, with their member budget and model access. Linked members only refuses everyone else. the integration's own key
Allowlists Answer in any channel the app is in, or only listed channels; answer DMs or not. any channel, DMs on
Length The longest answer in output tokens. 2,000
Books to key group Which key group's keys the answers book to. the oldest key group

Answers go through your routing, prompt and response filters, the secret scanner, model access, budgets and the org's spend cap, like any request; a refusal shows in Slack in the cloud's words. Answers appear in Requests as source:slack.

The question is sealed while it waits and deleted once answered (never kept past a day). The answer lives in Slack, not in venom; the Slack page lists each answer's time, origin, gear, model, status, tokens and cost.

Pause keeps acknowledging Slack and answers nothing. Disconnect deletes the credentials, channel gears and links and revokes every key the bot used; delete the app in Slack too.

Troubleshooting

Symptom Fix
The events URL won't verify Save the signing secret first, then Retry. A bad signature shows on the Slack page as the last problem.
not_in_channel Invite the app to the channel. A /venom question in a channel the app isn't in is answered through the command's response instead.
Nothing happens in a channel With Listed channels only, add the channel under Channel gears.

Linear and Jira intake

Hand an issue to venom and a machine you control opens a pull request for it:

  1. Someone adds the venom label to an issue (or assigns it to your bot user).
  2. Linear or Jira calls Venom Cloud's webhook, signed with your webhook's secret, and the cloud queues a job.
  3. A runner (venom intake run on a machine with the repository) claims it, comments that venom picked it up, and runs venom headless on the issue in a fresh git worktree on the branch venom/<key>-<slug>.
  4. The runner commits, pushes and opens the pull request with gh.
  5. The cloud comments on the issue with the PR link, the cost and the agent's summary, and moves its status (for example to In Review). A failed job's comment says what stopped it and links the console's retry.

Connect Linear

On Integrations → Linear (org admins):

  1. In Linear, Settings → API → Webhooks → New webhook. Paste the URL the console shows (https://<your cloud>/api/integrations/linear/<id>/webhook) and tick Issues only. Copy its signing secret.
  2. Create a personal API key (ideally a bot account's) under Settings → Security & access.
  3. Paste both into the console's Credentials and save; the key is checked against your workspace first.
  4. Under What venom picks up, set the repository (acme/api, or a git URL), optionally a repository per team (ENG=acme/api), the gear, the spend cap per job and the status names for picked up, PR open and failed. To trigger by assignment as well as by label, set the bot user's id.

Connect Jira Cloud

On Integrations → Jira:

  1. In Jira, Settings → System → WebHooks → Create a WebHook (Jira admin). Paste the console's URL, tick Issue: created and Issue: updated, and generate a Secret. To send less, add the JQL labels = venom.
  2. Create an API token at id.atlassian.com → Security → API tokens for the account venom comments as.
  3. In the console, enter your site (acme.atlassian.net), that account's email, the token and the webhook secret. They are checked against your site before they are kept.
  4. Set the repository, gear, cap and transition names as for Linear. Transitions match by their name or by the name of the status they lead to.

Jira's OAuth (3LO) apps are not supported; an API token is the supported path.

Run a runner

On any machine with the repository checked out and gh signed in:

venom cloud login
venom intake run --name build-box --repos ~/src --max-usd 5
Flag What it does Default
--name The runner's name in the console. the host name
--repos The folder your clones live in: acme/api is ~/src/acme/api or ~/src/api. A job whose repository is a git URL is cloned there.
--max-usd The most one job may spend on this machine; a job with a higher cap waits for another runner. 5
--risk low answers every approval no; medium lets the agent edit files; high also runs commands (tests, builds) in its worktree. medium
--draft Open draft pull requests. off
--once Work on at most one job, then exit. off

The runner only polls, so nothing listens on the machine. Each job's model calls use a key the cloud minted for that job, with a hard budget of the job's cap, revoked when it ends; the runner's own login key is never given to the agent. git and gh use the machine's own credentials. Background agents covers venom intake in full.

Watch and steer

Integrations → Intake jobs lists every job with its status (Queued, Running, PR opened, No changes, Failed, Hit cap, Cancelled), its cost against its cap, the pull request and the runner, plus the runners with their repositories and whether they are online. Org admins can cancel a live job (its key is revoked at once), retry an ended one, remove a runner, pause intake or disconnect the tracker. Spend is booked as source: intake and counts toward the org's budgets and spend cap.