Self-host an open-source Slack agent, runtime included

The Slack app half carries messages

A Slack app is a bot token, a signing secret and a subscription to the events Slack sends it. It receives a mention and posts a reply. It holds no tool credentials, no agent prompt, no record of what ran last week. That is the first half, and it is the half most products mean when they sell you a Slack agent.

Kortix connects it either way. On Kortix Cloud, Add to Slack walks through the shared app. Otherwise kortix channels manifest prints an app manifest. You create the app at api.slack.com from it, install it, and connect it with the bot token and signing secret in the first code panel. Your own app serves one project, so it skips the workspace commands.

A self-hosted instance needs the Slack, Microsoft and AgentMail credentials for the managed paths. An operator who will not hold a vendor's app credentials takes the manual path instead. Slack's own docs tell you how to add a bot. They do not tell you where the key to your CRM lives, or who can read it.

The runtime half holds the work

The second half is a git repo and the platform that runs it. kortix.yaml sits at the root. It declares the default agent, what each agent may reach, the connectors, the triggers, the secret names and the grants. Three lines are enough to start:

# yaml-language-server: $schema=https://kortix.com/schema/kortix.v2.schema.jsonkortix_version: 2default_agent: kortix

The schema line earns its place. An editor validates and completes every key you add after it, and kortix validate runs the same check before a push and again at merge. A broken grant fails in review, before it reaches a Slack thread.

Connectors are where your company's tools come in. Kortix stores the credential, picks the account a call runs as, applies the project's policies and records every call. Connector credentials are brokered server-side and never enter the machine. Which half holds the key decides what a stolen session can reach.

What stays on your network, and what calls out

The runtime is a platform you place yourself: run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free, and the docs cover the install. On your server you run the full platform: web app, API, database, and the services that start sessions. Your repo, your policies and your connector credentials sit there with it.

Sessions do not. Kortix runs them on Platinum sandboxes, and the instance must be reachable from the internet so those sandboxes can call back. Budget a public hostname, TLS on ports 80 and 443, and a wildcard DNS record for previews.

The honest version of the promise is narrower than most marketing, and more useful. Code, policies and credentials stay where you put them. A session still reads the project's files, so the data it works on passes through the sandbox while the job runs. What stays out of that sandbox is the connector credential, which Kortix spends on the server. A team that needs the sandbox itself sealed off, with no route out, is buying a different product.

One thread, one sandbox, one branch

One Slack thread is one session. The first message starts it, later messages continue it, and it survives the sandbox stopping and resuming. One isolated sandbox per session. Each session has its own isolated machine and branch.

A shared channel copes because of that. Ten mentions on a Monday become ten sessions on ten machines, each with a branch. A long report in one thread does not queue behind a quick lookup in another. Ask what the agent changed and the answer is a branch, not a transcript.

Approval rules are a file you can diff

Every connector action carries one policy: always_run, require_approval or block, shown in the app as Allow, Ask, Block. A held call stops before it runs. The agent's turn pauses, a card lists the action and the arguments the connector will receive, and the turn resumes with your decision. Nothing reaches the CRM, the inbox or the deploy key before that.

The project default is default_mode under policy: in kortix.yaml, allow_all or risk, starting at allow_all. Per-action rules are what teams tighten first. Those rules are text in the repo, so a change to them lands as a diff with an author and a reviewer. A settings page shows the current value and nothing about how it got there.

What a team trades for it

Self-hosting moves operator work onto your side. kortix-updater checks once a day on the stable channel by default; kortix self-host update applies a release on demand, and kortix self-host rollback --release <version> goes back. DNS, TLS, backups and the update window are yours. Each project needs its own model key, because a self-hosted instance has no Kortix-managed models. Close sign-up after your team joins, or anyone who reaches the instance can create a confirmed account.

In exchange, the half that holds your tool credentials answers to your change process and your auditors. The Slack app stays the thin, replaceable piece it should have been.

• Read the guide: Self-hosted AI agents.