Configuration

Classes for configuring flaude machine instances and repository specifications.

MachineConfig dataclass

MachineConfig(image=DEFAULT_IMAGE, claude_code_oauth_token='', github_username='', github_token='', prompt='', repos=list(), region=DEFAULT_REGION, vm_size=DEFAULT_VM_SIZE, vm_cpus=DEFAULT_VM_CPUS, vm_memory_mb=DEFAULT_VM_MEMORY_MB, auto_destroy=DEFAULT_AUTO_DESTROY, env=dict(), metadata=dict(), output_format='', volume_id='', volume_mount_path='/data', session_id='')

Configuration for a flaude Fly.io machine.

Attributes:

Name	Type	Description
image	str	Docker image reference for the machine.
claude_code_oauth_token	str	OAuth token for Claude Code authentication.
github_username	str	GitHub username for repo cloning.
github_token	str	GitHub personal access token for repo cloning.
prompt	str	The Claude Code prompt to execute.
repos	list[str | RepoSpec]	List of repositories to clone before running the prompt. Each entry can be a plain URL string or a :class:RepoSpec with optional branch and target directory.
region	str	Fly.io region to launch in.
vm_size	str	Fly.io VM preset size (e.g. performance-2x).
vm_cpus	int	Number of vCPUs.
vm_memory_mb	int	Memory in megabytes.
auto_destroy	bool	Whether to auto-destroy the machine when it exits.
env	dict[str, str]	Additional environment variables to set on the machine.
metadata	dict[str, str]	Arbitrary key-value metadata attached to the machine.

RepoSpec dataclass

RepoSpec(url, branch='', target_dir='')

Specification for a repository to clone on machine startup.

Attributes:

Name	Type	Description
url	str	Repository URL (e.g. https://github.com/org/repo).
branch	str	Optional branch/tag/ref to check out after cloning. Defaults to the repository's default branch when empty.
target_dir	str	Optional target directory name under /workspace. Defaults to the repo name derived from the URL when empty.

build_machine_config

build_machine_config(config)

Build the Fly.io Machines API create-machine payload.

Parameters:

Name	Type	Description	Default
config	MachineConfig	A :class:MachineConfig describing the desired machine.	required

Returns:

Type	Description
dict[str, Any]	A dict suitable for JSON-serialising and POSTing to
dict[str, Any]	POST /v1/apps/{app}/machines.

Raises:

Type	Description
ValueError	If required fields are missing.

Source code in flaude/machine_config.py

def build_machine_config(config: MachineConfig) -> dict[str, Any]:
    """Build the Fly.io Machines API create-machine payload.

    Args:
        config: A :class:`MachineConfig` describing the desired machine.

    Returns:
        A dict suitable for JSON-serialising and POSTing to
        ``POST /v1/apps/{app}/machines``.

    Raises:
        ValueError: If required fields are missing.
    """
    if not config.claude_code_oauth_token:
        raise ValueError("claude_code_oauth_token is required")
    if not config.prompt:
        raise ValueError("prompt is required")

    # Build environment variables — required ones first, then user overrides
    env_vars: dict[str, str] = {
        "CLAUDE_CODE_OAUTH_TOKEN": config.claude_code_oauth_token,
        "FLAUDE_PROMPT": config.prompt,
    }

    if config.github_username:
        env_vars["GITHUB_USERNAME"] = config.github_username
    if config.github_token:
        env_vars["GITHUB_TOKEN"] = config.github_token

    # Repos serialised as JSON array of {url, branch?, target_dir?}
    if config.repos:
        normalised = _normalise_repos(config.repos)
        env_vars["FLAUDE_REPOS"] = _serialise_repos(normalised)

    if config.output_format:
        env_vars["FLAUDE_OUTPUT_FORMAT"] = config.output_format

    if config.session_id:
        env_vars["FLAUDE_SESSION_ID"] = config.session_id
        env_vars["CLAUDE_CONFIG_DIR"] = f"{config.volume_mount_path}/claude"

    # Merge user-supplied env vars (they can override defaults if needed)
    env_vars.update(config.env)

    # Machine metadata — useful for tracking / cleanup
    metadata: dict[str, str] = {
        "managed_by": "flaude",
    }
    metadata.update(config.metadata)

    if config.session_id:
        metadata["session_id"] = config.session_id

    payload: dict[str, Any] = {
        "region": config.region,
        "config": {
            "image": config.image,
            "env": env_vars,
            "guest": {
                "cpu_kind": "performance",
                "cpus": config.vm_cpus,
                "memory_mb": config.vm_memory_mb,
            },
            "auto_destroy": config.auto_destroy,
            "restart": {
                "policy": "no",
            },
            "metadata": metadata,
        },
    }

    # Add volume mount for session persistence
    if config.volume_id:
        payload["config"]["mounts"] = [
            {
                "volume": config.volume_id,
                "path": config.volume_mount_path,
            }
        ]

    return payload