Integrations - Slack, Linear and Jira
Connect your own Slack app so @venom answers in threads, and your Linear or Jira so labelled issues become pull requests from runners you control.
Each integration is your own app: you create it in your own Slack workspace, Linear workspace or Jira Cloud site and paste its credentials into the console. Venom registers nothing on any account, and nothing is sent anywhere until an admin connects it. Credentials are sealed in the vault, so the deployment needs VENOM_VAULT_KEYS; without it connecting answers 503 vault_not_configured.
| Page | Permission | What |
|---|---|---|
/integrations |
org:read (connect: org:manage) |
A card per integration this cloud offers, with its status in words. |
/integrations/slack |
org:read (change: org:manage) |
Slack setup in three steps, then the connection, answer settings, channel gears, linked members, the latest answers with cost, Pause and Disconnect. |
/integrations/slack/link |
Any signed-in member | Confirms a /venom link code from Slack, tying your Slack user to your membership. |
/integrations/linear |
org:read (change: org:manage) |
Connect a Linear workspace for issue intake. |
/integrations/jira |
org:read (change: org:manage) |
Connect a Jira Cloud site for issue intake. |
/integrations/intake |
logs:read (cancel, retry, remove runner: org:manage) |
Intake jobs with status, cost against the cap and the pull request; runners and how to start one. |
Statuses: pending (created, credentials missing), active (credentials in and checked), paused (acknowledges events, does nothing).
Slack
Mention @venom in a channel, DM it, or type /venom <question>. It answers in the thread with one of your gears, streams the answer as it arrives, and ends with a line naming the gear, the model, the cost, the tokens and whose budget paid.
Set up
- Integrations → Slack → Connect Slack. The page shows an app manifest with your cloud's URLs.
- In Slack, create an app from an app manifest in your workspace and paste the JSON. It asks for the bot scopes
app_mentions:read,chat:write,commands,im:history,channels:history,groups:historyonly. - Install it, then paste the Signing secret and the Bot User OAuth Token (
xoxb-…) and click Save and check. The token is checked once with Slack'sauth.test; a refusal answers400 slack_rejectedwith Slack's reason. Only the last four characters are shown afterwards. - In the app's Event Subscriptions, click Retry next to the request URL. Step three turns green when Slack's first signed request arrives.
- Invite the bot to a channel (
/invite @venom) and mention it.
Settings
| Setting | Default | What |
|---|---|---|
| Default gear | the org's default gear | The gear that answers when the channel has none. Its first main model answers with its thinking level. |
| Channels | any channel the app is in | Or only listed channels (those with a channel gear row). An unlisted mention is ignored silently. |
| Answer DMs | on | Whether direct messages are answered. |
| Linked members only | off | Unlinked users get a prompt to run /venom link instead of an answer. |
| Max tokens | 2,000 | The longest answer in output tokens. |
| Books to key group | the oldest key group | Whose keys book the answers. |
| Channel gears | none | A gear per channel. Owners and admins with a linked Slack user can also set it with /venom gear <name> (/venom gear default clears it). |
Slash commands: /venom help, /venom link (a one-time code valid 15 minutes, confirmed at /integrations/slack/link), /venom gear, /venom gear <name|default>, and /venom <question>.
Every answer goes through your routing, prompt and response filters, the secret scanner, model access, budgets and spend cap like any request, and appears under Requests as source:slack. A refusal is posted in the cloud's own words. A linked member's answers use a key of their own, so their member budget and role apply; everyone else uses the integration's service key.
The question is sealed while it waits and deleted once answered (never kept past a day). Answer records are kept 90 days. Slack retries are deduplicated by event id; a stuck answer is retried up to 3 times.
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.
Linear and Jira intake
Label an issue venom (or assign it to the configured user) and it becomes a job. A runner on a machine you control picks it up, works in a git worktree, opens a pull request with gh, and reports back. The cloud comments on the issue (the PR link, the cost, the agent's summary or what stopped it) and moves its status. The cloud runs no agent and holds no repository.
Connect
Linear (/integrations/linear) |
Jira Cloud (/integrations/jira) |
|
|---|---|---|
| Credentials | A personal API key (or OAuth token) and a webhook secret | Site (<name>.atlassian.net), account email, API token, webhook secret |
| Checked on save | One GraphQL viewer/organization query |
GET /rest/api/3/myself on the site |
| Webhook to create | /api/integrations/linear/{id}/webhook (shown on the page) |
/api/integrations/jira/{id}/webhook (shown on the page) |
| Trigger | Issue created with the label, label added, or assigned to the configured user | Issue created with the label or assignee, label added, or assigned |
Settings for both:
| Setting | Default | What |
|---|---|---|
| Trigger label | venom |
The label that hands an issue to venom. |
| Repository | required | The default repository: a name your runners know, or a git URL without credentials. |
| Repositories per team/project | none | Team or project key → repository. |
| Base ref | the repository's default | The branch PRs target. |
| Gear | org default | Its main model and thinking level run the agent. |
| Max $ per job | 2 (at most 100) | Each job gets a key with this hard budget. |
| States | none | Names of the started, review and failed states to move the issue to; empty leaves the status. |
| Comment on start | on | Comment when a runner picks the job up. |
The integration is pending until both secrets are saved and checked and a repository is set.
Run a runner
On a machine with the repositories, git and gh signed in, and a key group's vck_ key:
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…
venom intake run --repos ~/src --max-usd 2venom intake run accepts --name, --repos <dir>, --max-usd, --risk low|medium|high, --draft and --once. The runner works under each job's own key, never yours, and stops at the job's cap.
Jobs
/integrations/intake lists jobs (queued, running, done, no changes, failed, capped, lost, cancelled) with live cost against the cap and the PR link, and runners (online if seen within 2 minutes). Cancel revokes the job's key at once. Retry fetches the issue again. Remove on a runner fails its running jobs; queued ones wait for another runner. A job runs at most 4 hours; a queued job nobody claims in 7 days fails. Disconnecting an integration cancels its live jobs and keeps the history.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Slack events URL won't verify | Save the signing secret first, then click Retry in Slack. A bad signature shows on the Slack page as the last problem. |
not_in_channel |
Invite the app to the channel. |
| Nothing happens in a channel | With "Listed channels only", add a channel gear row for it. |
503 vault_not_configured |
The deployment has no VENOM_VAULT_KEYS (Self-hosting). |
| Labelled issue does nothing | The integration is pending or paused, the webhook secret differs, or no runner serves that repository. Check the page's last error. |
Job ends capped |
It reached Max $ per job. Raise the cap and Retry. |