Skip to main content

flaude

CI PyPI Python License: MIT Docs

On-demand Claude Code execution on Fly.io machines.

Spin up VMs, run Claude Code prompts against your repos, stream the output back, and auto-destroy the machines when done. Or use persistent sessions for multi-turn conversations where Claude Code remembers the full context between prompts.

How it works

Your code                    Fly.io
───────                      ──────
MachineConfig ──► create VM ──► clone repos
                                  │
                              run Claude Code
                                  │
            ◄── stream logs ◄─ stdout/stderr
                                  │
              destroy VM ◄──── exit
  1. A Docker container with Claude Code, git, and gh CLI pre-installed boots on Fly.io
  2. The entrypoint clones your specified repos into /workspace
  3. Claude Code runs your prompt in print mode (-p)
  4. Logs stream back to your process via HTTP log drains (NDJSON)
  5. The machine is always destroyed after completion (guaranteed via try/finally)

Install

pip install flaude

Requires Python 3.11+. The only runtime dependency is httpx.

Prerequisites

  • Fly.io account with a valid FLY_API_TOKEN
  • Claude Code OAuth token for authenticating Claude Code on the machine
  • GitHub credentials (username + PAT) if cloning private repos
  • Docker (only needed if building/pushing the container image yourself)

Quick start

Run a prompt and wait for the result

import asyncio
from flaude import MachineConfig, ensure_app, run_and_destroy

async def main():
    app = await ensure_app("my-flaude-app")

    config = MachineConfig(
        claude_code_oauth_token="sk-ant-oat-...",
        github_username="you",
        github_token="ghp_...",
        prompt="Find and fix any type errors in src/",
        repos=["https://github.com/you/your-repo"],
    )

    result = await run_and_destroy(app.name, config)
    print(f"Exit code: {result.exit_code}")

asyncio.run(main())

Stream logs in real time

from flaude import MachineConfig, run_with_logs

async def main():
    config = MachineConfig(
        claude_code_oauth_token="sk-ant-oat-...",
        prompt="Refactor the auth module to use JWT",
        repos=["https://github.com/you/your-repo"],
    )

    async with await run_with_logs("my-flaude-app", config) as stream:
        async for line in stream:
            print(line)

    result = await stream.result()
    print(f"Done: exit={result.exit_code}")

Run multiple prompts concurrently

from flaude import ConcurrentExecutor, ExecutionRequest, MachineConfig

async def main():
    executor = ConcurrentExecutor("my-flaude-app", max_concurrency=3)

    requests = [
        ExecutionRequest(
            config=MachineConfig(prompt="Add tests for auth", ...),
            tag="auth-tests",
        ),
        ExecutionRequest(
            config=MachineConfig(prompt="Add tests for billing", ...),
            tag="billing-tests",
        ),
    ]

    batch = await executor.run_batch(requests)
    print(f"{batch.succeeded}/{batch.total} succeeded")

Multi-turn sessions

from flaude import MachineConfig, create_session, run_session_turn, destroy_session

async def main():
    config = MachineConfig(
        claude_code_oauth_token="sk-ant-oat-...",
        prompt="Review src/ for security issues and list them.",
        repos=["https://github.com/you/your-repo"],
    )

    # First turn — creates a persistent session
    session, result = await create_session("my-flaude-app", config)
    print(f"Session: {session.session_id}, exit: {result.exit_code}")

    # Second turn — Claude remembers the first conversation
    config2 = MachineConfig(
        claude_code_oauth_token="sk-ant-oat-...",
        prompt="Fix the top 3 security issues you found.",
    )
    result2 = await run_session_turn(
        session.app_name, session.machine_id, config2
    )

    # Cleanup
    await destroy_session(session.app_name, session)

API overview

Configuration

Class Purpose
MachineConfig Full machine configuration: prompt, repos, credentials, VM size, region
RepoSpec Repository spec with optional branch and target directory

Execution

Function / Class Purpose
run_and_destroy() Run prompt, wait for exit, destroy machine. Raises on failure.
run() Same as above but doesn't raise on non-zero exit.
run_with_logs() Run with real-time log streaming via async iterator.
ConcurrentExecutor Run multiple prompts in parallel with optional concurrency limits.

Sessions

Function / Class Purpose
create_session() Create a persistent session (volume + machine + first prompt).
run_session_turn() Run a follow-up prompt on an existing session.
destroy_session() Destroy session (machine + volume).
Session Dataclass tracking session state across turns.

App & machine management

Function Purpose
ensure_app() Get or create a Fly.io app
create_app() / get_app() Explicit app create/get
create_machine() Create a Fly machine from config
stop_machine() / destroy_machine() Machine lifecycle control
start_machine() / update_machine() Start stopped machines, update config

Volume management

Function / Class Purpose
FlyVolume Volume metadata dataclass
create_volume() Create a Fly volume for session persistence
list_volumes() / destroy_volume() List or destroy volumes

Log infrastructure

Class / Function Purpose
LogDrainServer HTTP server that receives Fly.io log drain POSTs
LogCollector Routes log lines to per-machine async queues
LogStream Async iterator over a machine's log output with timeout support
StreamingRun Combined async iterator + context manager for streaming executions
fetch_machine_logs() Fetch historical logs from Fly platform API (works after machine exits)

Image management

Function Purpose
ensure_image() Build and push the Docker image if needed
docker_build() / docker_push() Explicit build/push

Results & errors

Class Purpose
RunResult Exit code, final state, and machine ID
MachineExitError Raised on non-zero exit; includes captured log tail
BatchResult Aggregated results from concurrent execution
ExecutionResult Per-request result within a batch

Configuration reference

MachineConfig fields:

Field Default Description
image ghcr.io/ravi-hq/flaude:latest Docker image
claude_code_oauth_token (required) Claude Code auth token
github_username "" GitHub username for private repos
github_token "" GitHub PAT for private repos
prompt (required) The Claude Code prompt to execute
repos [] Repos to clone (URLs or RepoSpec objects)
region "iad" Fly.io region
vm_size "performance-2x" VM preset
vm_cpus 2 vCPUs
vm_memory_mb 4096 RAM in MB
auto_destroy True Auto-destroy on exit
output_format "" Output format ("stream-json" for structured NDJSON)
volume_id "" Fly volume ID for session persistence
volume_mount_path "/data" Volume mount path inside the container
session_id "" UUID for Claude Code session continuity
env {} Additional environment variables
metadata {} Machine metadata key-value pairs

Environment variables

Set in your local environment:

Variable Purpose
FLY_API_TOKEN Authenticate with the Fly.io Machines API

Set automatically on the machine by flaude:

Variable Purpose
CLAUDE_CODE_OAUTH_TOKEN Claude Code authentication
GITHUB_USERNAME Git credential for repo cloning
GITHUB_TOKEN Git credential for repo cloning
FLAUDE_REPOS JSON array of repo specs
FLAUDE_PROMPT The prompt string
FLAUDE_SESSION_ID Session UUID (when using sessions)
CLAUDE_CONFIG_DIR Claude Code config dir on volume (when using sessions)

Development

git clone https://github.com/ravi-hq/flaude.git
cd flaude
uv sync --extra dev      # install all dev dependencies
make test                # run unit tests
make check               # lint + type check + security scan

See CONTRIBUTING.md for the full contribution guide.

E2E validation tests

E2E tests spin up real Fly.io machines, run Claude Code, and verify the full lifecycle. They are excluded by default — pytest alone never runs them.

Prerequisites

All required tokens are in .env:

Token Purpose
FLY_API_TOKEN Authenticates Fly.io API calls from your machine
CLAUDE_CODE_OAUTH_TOKEN Forwarded into the Fly machine for Claude Code auth
GITHUB_USERNAME Git clone auth (optional, for private repo tests)
GITHUB_TOKEN Git clone auth (optional, for private repo tests)

Optional:

Env var Purpose
FLAUDE_E2E_PRIVATE_REPO Full URL of a private repo to test cloning

The Docker image ghcr.io/ravi-hq/flaude:latest must be pushed before running E2E tests:

source .env && python -c "
import asyncio
from flaude import ensure_image
asyncio.run(ensure_image('flaude'))
"

The image is built for linux/amd64 (required by Fly.io) regardless of your host architecture.

Running E2E tests

source .env && pytest -m e2e -v

That's it. Each test creates a real Fly machine, runs a prompt, checks the output, and destroys the machine. Expect ~1-3 minutes per test.

What the tests validate

Test What it proves
test_smoke_run_and_destroy Full lifecycle works: create machine → run prompt → exit 0 → destroy
test_machine_logs Fetches logs via Fly platform API; verifies [flaude:exit:0] marker
test_public_repo_clone Public GitHub repo clones successfully before Claude Code runs
test_private_repo_clone Private repo clone with credentials (skipped if creds absent)
test_machine_cleanup_on_success Machine is actually destroyed after run (404 on get)

Running specific tests

# Just the smoke test (fastest, ~1 min):
source .env && pytest -m e2e -v -k smoke

# Everything including unit tests:
source .env && pytest -m "" -v

License

See repository for license details.

Metadata

Release files for flaude 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flaude 0.6.1
File Size Uploaded Provenance Actions
flaude-0.6.1.tar.gz 232.1 kB With provenance Details for flaude-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flaude 0.6.1
File Interpreter ABI Platform Actions
flaude-0.6.1-py3-none-any.whl Python 3 none any Details for flaude-0.6.1-py3-none-any.whl

Total release size: 274.5 kB

Release files / flaude-0.6.1.tar.gz

Download URL flaude-0.6.1.tar.gz
Size 232.1 kB
Tags Source
SHA-256 checksum
How to use checksums
82c97b839c95044610bea328228802b1115d985358e0e3b0b73b4b1f6b4b05d2
BLAKE2b-256 checksum
How to use checksums
a0a1e594e898358cf18c1374244d9e338ac9ff0ef5794ebdcd2dfbf6bfdac910
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.

Transparency log

Release files / flaude-0.6.1-py3-none-any.whl

Download URL flaude-0.6.1-py3-none-any.whl
Size 42.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4781fb5e3bfe49d4103c7f6d206a498b1a73ea7eac540b7709cf00ca1593cffa
BLAKE2b-256 checksum
How to use checksums
5c681e671b5fd7796de75fb59ef3b3458341fdd10aff1c2e1cd22d14b2d6dd5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.

Transparency log

Security for flaude 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flaude-0.6.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page