Integrations

Integrations

Slack-Native Operations

Klanker Maker's Slack integration is the primary surface for talking to agents at scale. Phases 62–68 build a complete bidirectional control plane.

What you get per sandbox

When notifySlackPerSandbox: true:

1. A dedicated channel - #sb-{sandbox-id} is created on km create, archived on km destroy (configurable). Operator is invited via Slack Connect from their own workspace.
2. Lifecycle notifications - sandbox creation, TTL warnings, budget thresholds, errors, Stop hooks all post to the channel.
3. Bidirectional chat (notifySlackInboundEnabled: true) - Send a Slack message; the bridge verifies the Slack signing secret, looks up the sandbox via the slack_channel_id-index GSI, enqueues to the per-sandbox SQS FIFO queue. A systemd poller on the sandbox dequeues, exports KM_SLACK_THREAD_TS, and dispatches claude -p with session continuity (resumed via km-slack-threads DDB lookup).
4. Per-turn transcript streaming (notifySlackTranscriptEnabled: true) - Each assistant turn streams to the Slack thread as it happens. Tool calls render as one-liners. On Stop, the full session uploads as a gzipped JSONL file. Independent of the claude -p cost - runs as a hook.
5. :eyes: ack reactions - The bridge adds 👀 to the originating message the moment it's enqueued, before the agent has even seen it. Lets the human know it's been received.

Trust model

The bot token never leaves AWS. Sandboxes don't have it. Outbound Slack notifications go through the bridge Lambda with Ed25519-signed payloads (same key the sandbox uses for email). Inbound Slack events are verified against the signing secret using HMAC-SHA256 before the bridge will dispatch them. The Slack App's bot scopes are minimal: chat:write, channels:manage, conversations.connect:write, groups:write, channels:history, groups:history, reactions:write, files:write.

Setup, in one block

# One-time: rebuild km, build sidecars, deploy bridge + DDB tables
make build && km init --sidecars && km init

# Bootstrap Slack: validates token, creates shared channel, sends Slack Connect invite,
# deploys bridge Lambda, writes signing secret to SSM
km slack init --bot-token xoxb-… --invite-email ops@example.com --signing-secret …

# (paste the printed Events URL into Slack App → Event Subscriptions)
km slack test     # smoke-test through the bridge
km slack status   # show wiring

Profile flags

Field	Default	Effect
notifyEmailEnabled	true	SES email path; pair with Slack or use standalone
notifySlackEnabled	false	Master switch for Slack delivery
notifySlackPerSandbox	false	Provision #sb-{id} channel; archive at destroy
notifySlackChannelOverride	empty	Pin to existing channel ID (mutually exclusive with per-sandbox)
notifySlackInboundEnabled	false	SQS FIFO + sandbox poller for chat → Claude turns
notifySlackTranscriptEnabled	false	Stream per-turn output + upload final JSONL

See docs/slack-notifications.md for the full operator guide, including troubleshooting and the security model.

---

GitHub App Integration

Klanker Maker uses a GitHub App (not personal access tokens) to grant sandboxes scoped, short-lived git access.

km github                                      # manifest-flow App creation in browser
km configure github --discover --force         # discover installations across accounts

Per profile:

spec:
  sourceAccess:
    mode: allowlist
    github:
      allowedRepos:
        - my-org/api
        - my-org/infra
      allowedRefs: [main, "feature/*", "fix/*"]

What happens at create:

1. The compiler reads allowedRepos, looks up the matching App installation per repo owner, and provisions a per-sandbox SSM parameter holding the installation token.
2. The km-github-token-refresher Lambda runs on a schedule, refreshing the token before its 1-hour expiry.
3. Inside the sandbox, the HTTP proxy is configured to inject the token as Authorization: token … for *.github.com and *.githubusercontent.com requests - but only for paths matching allowedRepos. Other repos return 403 even if the agent has the URL.
4. Refs are enforced at the proxy layer too: git push to a non-allowlisted ref is rejected.

Multi-account is supported: install the App on multiple GitHub accounts/orgs, and km configure github --discover writes an installation key per account. The compiler matches org/repo to the right installation.

See docs/github.md for the full setup.

---

Multi-Agent Orchestration via Signed Email

Sandboxes communicate through digitally signed email (SES + Ed25519). Each sandbox gets a unique address derived from its ID (e.g., sb-a1b2c3d4@sandboxes.klankermaker.ai) and an Ed25519 key pair at creation time.

• Signing - outbound emails are signed with the sender's Ed25519 private key (stored in SSM, KMS-encrypted). The signature and sender ID are attached as X-KM-Signature and X-KM-Sender-ID headers.
• Verification - the receiver fetches the sender's public key from the km-identities DynamoDB table and verifies the signature. When verifyInbound: required, unsigned or invalid emails are rejected.
• Encryption - optional X25519 key exchange (NaCl box). When encryption: required, the sender encrypts the body with the recipient's public key. When encryption: optional, it encrypts if the recipient has a published key, plaintext otherwise.

Inside a sandbox, km-send and km-recv wrap the protocol:

# From inside any sandbox
km-send --to sb-x9y8z7@sandboxes.example.com --subject "results" --body output.json --attach data.tar.gz
km-recv --watch                    # poll inbox every 5s
km-recv --json | jq '.[0].body'    # for agent parsing

From the operator workstation, km email send and km email read do the same with full signature verification and auto-decryption.

This enables multi-agent pipelines where each worker is physically isolated but logically connected - with cryptographic proof of sender identity and optional confidentiality. Combined with km at scheduling, you can build pipelines like "every Monday at 9am, sb-A runs the smoke tests, on success emails sb-B which runs the deploy".

See docs/multi-agent-email.md for SES setup, IAM policy, signing protocol, and orchestration patterns.

---