airut 0.17.0

Sandboxed Claude Code over email and Slack

Airut

Sandboxed Claude Code over email and Slack. Named "Airut" (Finnish: herald/messenger).

Send a message — email or Slack — with instructions, and get results back in the same thread. Starting a new task is as simple as starting a new conversation. Airut handles everything behind the scenes: workspace creation, container isolation, network sandboxing, session persistence, and cleanup.

Self-hosted: your code and conversations never leave your infrastructure.

You → Email/Slack → Airut → Claude Code (container) → PR → Reply → You

Key Features

• Zero-friction tasking — send a message to start a task. No workspace setup, no session management, no cleanup.
• Defense-in-depth sandboxing — container isolation, network allowlist via proxy, and credential masking limit blast radius when agents run with full autonomy.
• Conversation persistence — reply to continue where you left off. Claude Code session context is maintained across messages.
• Task-to-PR foundation — combined with proper repo configuration (CLAUDE.md, CI tooling, branch protection), enables end-to-end autonomous workflows where agents push PRs for human review.
• Email and Slack channels — authenticate via DMARC (email) or workspace membership (Slack), with sender authorization per repo.
• Web dashboard — monitor running tasks and view network activity logs.

Quick Start

Prerequisites

• Linux (dedicated VM recommended, Debian 13 tested)
• uv, Git, and Podman (rootless)
• At least one channel per repository:
  • Email: Dedicated email account with IMAP/SMTP access
  • Slack: Slack workspace with app installation permissions

Install

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Airut from PyPI
uv tool install airut

Or install the latest development version from main:

uv tool install airut --from git+https://github.com/airutorg/airut.git

Configure

# Generate initial config at ~/.config/airut/airut.yaml
airut init

# Validate config and system dependencies
airut check

Deploy

# Install and start the systemd service
airut install-service

# Verify it's running
airut check

Update

airut update

How It Works

Each conversation runs in an isolated container with its own git workspace, Claude Code session, and sandboxed network. The recommended workflow has agents push PRs for your review — you review, leave comments, and reply to iterate.

You: "Add user authentication"
    ↓
Agent: works → pushes PR → replies with PR link
    ↓
You: review PR, leave comments
    ↓
You: reply "Address the review comments"
    ↓
Agent: reads comments → fixes → updates PR → replies
    ↓
You: approve and merge

Sandbox Library

The airut.sandbox module is a standalone library for safe containerized execution of headless Claude Code. It can be used independently of the gateway to run Claude Code in isolated containers from any Python application — CI pipelines, automation scripts, custom integrations, or your own agent orchestrator.

Core capabilities:

• Container lifecycle — two-layer image build, execution, and cleanup via Podman or Docker
• Network isolation — transparent DNS-spoofing proxy enforcing a domain allowlist, with no HTTP_PROXY env vars or iptables rules needed
• Secret masking — surrogate credential injection so real secrets never reach the container, with proxy-side replacement on egress
• Event streaming — append-only log of Claude's streaming JSON output, safe for concurrent reads during execution
• Outcome classification — typed Outcome enum (success, timeout, prompt-too-long, session-corrupted, container-failed) so callers match on outcomes instead of parsing strings

Quick example:

from airut.sandbox import Sandbox, SandboxConfig, Mount, ContainerEnv, Outcome

sandbox = Sandbox(SandboxConfig())
sandbox.startup()

image = sandbox.ensure_image(dockerfile, context_files)
task = sandbox.create_task(
    execution_context_id="my-run-1",
    execution_context_dir=run_dir,
    image_tag=image,
    mounts=[Mount(host_path=repo, container_path="/workspace")],
    env=ContainerEnv(variables={"ANTHROPIC_API_KEY": key}),
    timeout_seconds=600,
)
result = task.execute("Fix the failing tests")

if result.outcome == Outcome.SUCCESS:
    print(result.response_text)

sandbox.shutdown()

See the sandbox spec for full architecture details and API reference.

Documentation

Full documentation is available on GitHub:

• Deployment Guide — installation, configuration, and service management
• Architecture — system architecture and data flow
• Security Model — channel auth, container isolation, credential handling
• Repo Onboarding — how to onboard a new repository
• Agentic Operation — message-to-PR workflow patterns

Links

• GitHub Repository
• Full README

License

MIT License. See LICENSE for details.