offbox 0.1.0__py3-none-any.whl

offbox/cli/host.py

@@ -0,0 +1,313 @@
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+from pydantic import Field, TypeAdapter
+from typer._click import Context
+from typer.core import TyperCommand
+
+from offbox import console
+from offbox.config import Model
+from offbox.errors import OffboxError, PreconditionError, UsageError
+from offbox.host import select_host
+from offbox.host.auto import host_activity, timer_status
+from offbox.host.auto import reap as reap_hosts
+from offbox.host.destroy import destroy_host
+from offbox.host.timer import health as timer_health
+from offbox.host.timer import install as install_reaper
+from offbox.host.timer import installed as timer_installed
+from offbox.host.timer import remove as remove_reaper
+from offbox.host.usage import shared_usage, utc_now
+from offbox.host.warnings import HostWarning, dismiss_warning, read_warnings
+from offbox.paths import Paths
+from offbox.providers import validate_name
+from offbox.runner import Runner, SubprocessRunner
+from offbox.ssh import ssh_argv
+from offbox.state import HostState, StateStore
+
+app = typer.Typer(no_args_is_help=True, help="Create, register and manage hosts.")
+
+
+class HostSummary(Model):
+    name: str
+    provider: str
+    ip: str
+    envs: int
+    reachable: bool
+    phase: Literal["creating", "initializing", "ready"]
+    default: bool
+    auto: bool = False
+    idle_seconds: int | None = None
+    last_activity: datetime | None = None
+    reaps_after: datetime | None = None
+
+
+class HostReport(Model):
+    hosts: list[HostSummary] = Field(default_factory=list[HostSummary])
+    timer_installed: bool = False
+    timer_warning: str | None = None
+    warnings: list[HostWarning] = Field(default_factory=list[HostWarning])
+
+
+def host_report(paths: Paths, runner: Runner) -> HostReport:
+    state = StateStore(paths.state).read()
+
+    def describe(host: HostState) -> HostSummary:
+        reachable = False
+        if host.address:
+            try:
+                reachable = (
+                    runner.run(ssh_argv(host.name, ["true"], options=["-o", "ConnectTimeout=3"]), check=False, timeout=3).returncode == 0
+                )
+            except OffboxError:
+                reachable = False
+        activity = host_activity(paths, state, host) if host.auto else None
+        return HostSummary(
+            name=host.name,
+            provider=host.provider,
+            ip=host.address,
+            envs=sum(env.host == host.name for env in state.envs.values()),
+            reachable=reachable,
+            phase=host.phase,
+            default=state.default_host == host.name,
+            auto=host.auto,
+            idle_seconds=host.idle_seconds,
+            last_activity=activity,
+            reaps_after=activity + timedelta(seconds=host.idle_seconds) if activity is not None and host.idle_seconds else None,
+        )
+
+    with ThreadPoolExecutor(max_workers=min(8, max(1, len(state.hosts)))) as executor:
+        hosts = list(executor.map(describe, [host for _, host in sorted(state.hosts.items())]))
+    last_run, failure = timer_status(paths)
+    return HostReport(
+        hosts=hosts,
+        timer_installed=timer_installed(paths),
+        timer_warning=timer_health(paths, utc_now(), last_run, failure),
+        warnings=read_warnings(paths),
+    )
+
+
+def _when(moment: datetime) -> str:
+    return moment.astimezone().strftime("%Y-%m-%d %H:%M")
+
+
+def use_host(paths: Paths, name: str) -> None:
+    validate_name(name)
+    with StateStore(paths.state).transaction() as state:
+        if name not in state.hosts or state.hosts[name].phase != "ready":
+            raise PreconditionError(f"Host {name} is not ready or registered", "Create or initialise the host before selecting it.")
+        if state.hosts[name].auto:
+            raise PreconditionError(
+                f"Host {name} is auto-managed and cannot be the default", "Select it per project with env.host instead."
+            )
+        state.default_host = name
+    console.success(f"Default host: {name}")
+
+
+def _runner(ctx: typer.Context) -> SubprocessRunner:
+    value: object = ctx.find_root().obj
+    if not isinstance(value, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    return value
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Host name used in offbox commands and the offbox-NAME SSH alias.")] = "main",
+    provider: Annotated[str | None, typer.Option("--provider", help="Cloud provider: hetzner, gcp or a custom provider name.")] = None,
+    size: Annotated[str | None, typer.Option("--size", help="Provider machine type, for example ccx33 or e2-standard-4.")] = None,
+    region: Annotated[str | None, typer.Option("--region", help="Provider location or zone, for example fsn1 or us-east4-c.")] = None,
+    ssh_key: Annotated[
+        Path | None, typer.Option("--ssh-key", help="Private SSH key for the host. Default: ~/.ssh/id_ed25519, else ~/.ssh/offbox_ed25519.")
+    ] = None,
+) -> None:
+    """Provision a VM and wait for its bootstrap to complete."""
+    from offbox.host.create import CreateOptions, create_host
+
+    create_host(Paths.discover(), _runner(ctx), CreateOptions(name=name, provider=provider, size=size, region=region, ssh_key=ssh_key))
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    target: Annotated[str, typer.Argument(help="Existing server login as USER@ADDRESS; USER needs passwordless sudo.")],
+    name: Annotated[str, typer.Option("--name", help="Host name used in offbox commands.")] = "main",
+    port: Annotated[int, typer.Option("--port", min=1, max=65535, help="SSH port of the server.")] = 22,
+    host_key_fingerprint: Annotated[
+        str | None,
+        typer.Option(
+            "--host-key-fingerprint",
+            help="Expected SHA256:... ed25519 host key fingerprint (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub).",
+        ),
+    ] = None,
+    accept_host_key: Annotated[
+        bool, typer.Option("--accept-host-key", help="Trust the scanned host key without verification; prefer --host-key-fingerprint.")
+    ] = False,
+    ssh_key: Annotated[
+        Path | None,
+        typer.Option("--ssh-key", help="Private SSH key for the server. Default: ~/.ssh/id_ed25519, else ~/.ssh/offbox_ed25519."),
+    ] = None,
+) -> None:
+    """Bootstrap an existing server while preserving its owner's access."""
+    from offbox.host.init import InitOptions, init_host
+
+    init_host(
+        Paths.discover(),
+        _runner(ctx),
+        InitOptions(
+            target=target,
+            name=name,
+            port=port,
+            accept_host_key=accept_host_key,
+            host_key_fingerprint=host_key_fingerprint,
+            ssh_key=ssh_key,
+        ),
+        confirm=typer.confirm if sys.stdin.isatty() else None,
+    )
+
+
+@app.command("list")
+def list_hosts(
+    ctx: typer.Context,
+    json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False,
+    dismiss: Annotated[str | None, typer.Option("--dismiss", help="Clear the stored warning for this host name.")] = None,
+) -> None:
+    """List registered hosts, their reachability and auto-managed lifecycle."""
+    paths = Paths.discover()
+    if dismiss is not None:
+        validate_name(dismiss)
+        if dismiss_warning(paths, dismiss):
+            console.success(f"Dismissed the warning for {dismiss}")
+        else:
+            console.info(f"No warning stored for {dismiss}")
+        return
+    report = host_report(paths, _runner(ctx))
+    if json:
+        console.json_out(report)
+        return
+    if not report.hosts:
+        console.info("No hosts registered")
+    for host in report.hosts:
+        line = f"{host.name}  {host.provider}  {host.ip or 'pending'}  envs={host.envs}  reachable={'yes' if host.reachable else 'no'}  {host.phase}"
+        if host.auto:
+            idle = f"idle limit {host.idle_seconds // 60}m" if host.idle_seconds else "idle reaping off"
+            line += f"  auto ({idle}"
+            if host.last_activity is not None:
+                line += f", last used {_when(host.last_activity)}"
+            if host.reaps_after is not None:
+                line += f", reaped after {_when(host.reaps_after)}"
+            line += ")"
+        console.info(line)
+    for warning in report.warnings:
+        console.warn(f"{warning.message}. Fix: offbox host list --dismiss {warning.host} once checked.")
+    if report.timer_warning:
+        console.warn(report.timer_warning)
+    elif any(host.auto and host.idle_seconds for host in report.hosts) and not report.timer_installed:
+        console.info("Idle reaping needs the timer: offbox host reap --install-timer")
+
+
+@app.command()
+def use(name: Annotated[str, typer.Argument(help="Registered host to use by default.")]) -> None:
+    """Choose the default host."""
+    use_host(Paths.discover(), name)
+
+
+@app.command()
+def destroy(
+    ctx: typer.Context,
+    name: Annotated[str | None, typer.Argument(help="Host to destroy. Default: the default host.")] = None,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm without a prompt.")] = False,
+    forget: Annotated[
+        bool, typer.Option("--forget", help="For an unreachable SSH host: remove only the local record and leave the server untouched.")
+    ] = False,
+) -> None:
+    """Destroy a host and its environments."""
+    paths = Paths.discover()
+    host = select_host(paths, name)
+    envs = [env.name for env in StateStore(paths.state).read().envs.values() if env.host == host.name]
+    action = "Forgetting" if forget else "Destroying"
+    console.warn(f"{action} {host.name} loses environments: {', '.join(envs) if envs else '(none)'}")
+    if not yes:
+        if not sys.stdin.isatty():
+            flags = " --forget" if forget else ""
+            raise PreconditionError("Destruction requires --yes without a TTY", f"Run offbox host destroy {host.name}{flags} --yes.")
+        if not typer.confirm(f"{'Forget' if forget else 'Destroy'} host {host.name}?"):
+            raise PreconditionError("Destruction cancelled", "Run the command again when ready.")
+    destroy_host(paths, _runner(ctx), host.name, forget=forget)
+
+
+class HostSshCommand(TyperCommand):
+    def parse_args(self, ctx: Context, args: list[str]) -> list[str]:
+        if "--" in args:
+            index = args.index("--")
+            ctx.meta["offbox_remote_command"] = tuple(args[index + 1 :])
+            args = args[:index]
+        return super().parse_args(ctx, args)
+
+    def collect_usage_pieces(self, ctx: Context) -> list[str]:
+        return [*super().collect_usage_pieces(ctx), "[-- COMMAND [ARGS]...]"]
+
+
+@app.command(cls=HostSshCommand)
+def ssh(ctx: typer.Context, name: Annotated[str | None, typer.Argument(help="Host to open. Default: the default host.")] = None) -> None:
+    """Open a host shell or run a command after --."""
+    host = select_host(Paths.discover(), name)
+    if not host.address:
+        raise PreconditionError("Host has no recorded address", f"Run offbox host destroy {host.name} to clean up the pending host.")
+    raw: object = ctx.meta.get("offbox_remote_command", ())
+    command = TypeAdapter(list[str]).validate_python(raw)
+    tty = not command
+    if tty and not sys.stdin.isatty():
+        raise PreconditionError("Interactive SSH requires a TTY", "Pass a command after -- for noninteractive SSH.")
+    paths = Paths.discover()
+    with shared_usage(paths, host.name, "offbox host ssh"):
+        if select_host(paths, host.name) != host:
+            raise PreconditionError(f"Host {host.name} changed while starting", "Retry the command.")
+        code = _runner(ctx).stream(ssh_argv(host.name, command, options=["-t"] if tty else []), stdin=tty, tty=tty)
+    raise typer.Exit(code)
+
+
+@app.command()
+def reap(
+    ctx: typer.Context,
+    name: Annotated[str | None, typer.Argument(help="Auto-managed host to check. Default: every auto-managed host.")] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show what would be destroyed without changing anything.")] = False,
+    json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False,
+    install_timer: Annotated[
+        bool, typer.Option("--install-timer", help="Run the reaper every 15 minutes from launchd or systemd.")
+    ] = False,
+    remove_timer: Annotated[bool, typer.Option("--remove-timer", help="Remove the scheduled reaper.")] = False,
+    from_timer: Annotated[bool, typer.Option("--from-timer", hidden=True, help="Record this run as the scheduled reaper's.")] = False,
+) -> None:
+    """Destroy idle auto-managed hosts and hosts whose creation never finished."""
+    paths, runner = Paths.discover(), _runner(ctx)
+    if install_timer and remove_timer:
+        raise UsageError("Choose --install-timer or --remove-timer", "Run one of them.")
+    if install_timer:
+        install_reaper(paths, runner)
+        return
+    if remove_timer:
+        if remove_reaper(paths, runner):
+            console.success("Idle reaper removed")
+        else:
+            console.info("No idle reaper installed")
+        return
+    report = reap_hosts(paths, runner, name, dry_run=dry_run, source="timer" if from_timer else "manual")
+    if json:
+        console.json_out(report)
+    else:
+        if not report.hosts:
+            console.info("No auto-managed hosts")
+        for outcome in report.hosts:
+            action = "would destroy" if outcome.action == "destroy" else outcome.action
+            lost = f"; environments lost: {', '.join(outcome.lost_environments)}" if outcome.lost_environments else ""
+            message = f"{outcome.name}: {action} ({outcome.reason}{lost})"
+            if outcome.action == "failed":
+                console.error(message, outcome.error)
+            else:
+                console.info(message)
+    raise typer.Exit(report.exit_code)

offbox/cli/misc.py

@@ -0,0 +1,132 @@
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+
+from offbox import console
+from offbox.errors import OffboxError, UsageError
+from offbox.logs import follow_lines, stack_logs
+from offbox.naming import find_worktree
+from offbox.paths import Paths
+from offbox.runner import SubprocessRunner
+from offbox.status import Status
+from offbox.uninstall import uninstall as run_uninstall
+
+
+def _runner(ctx: typer.Context) -> SubprocessRunner:
+    runner: object = ctx.find_root().obj
+    if not isinstance(runner, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    return runner
+
+
+def status(ctx: typer.Context, json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False) -> None:
+    """Check this worktree's host, environment, sync, ports and stack."""
+    report = Status(Paths.discover(), _runner(ctx)).diagnose()
+    if json:
+        console.json_out(report)
+    else:
+        for check in report.checks:
+            if check.level == "ok":
+                console.success(check.message)
+            elif check.level == "warning":
+                console.warn(check.message)
+                console.info(f"  Fix: {check.fix}")
+            else:
+                console.error(check.message, check.fix)
+            if check.name == "ports":
+                for forward in report.ports.forwards:
+                    state = "active" if forward.active else "inactive"
+                    console.info(f"  localhost:{forward.local} → {forward.env}:{forward.remote} ({state})")
+    raise typer.Exit(report.exit_code)
+
+
+def logs(
+    ctx: typer.Context,
+    service: Annotated[str | None, typer.Argument(help="Compose service to show; requires --stack.")] = None,
+    follow: Annotated[bool, typer.Option("--follow", help="Keep streaming new lines.")] = False,
+    stack: Annotated[bool, typer.Option("--stack", help="Show the project's Compose stack logs instead of offbox's log.")] = False,
+) -> None:
+    """Read today's environment log or stream Compose logs with --stack [SERVICE]."""
+    if service is not None and not stack:
+        raise UsageError("A service requires --stack", "Run offbox logs --stack SERVICE.")
+    runner, paths = _runner(ctx), Paths.discover()
+    try:
+        if stack:
+            raise typer.Exit(stack_logs(paths, runner, follow=follow, service=service))
+        work = find_worktree(runner)
+        for line in follow_lines(paths, work.name, follow=follow):
+            console.text(line)
+    except KeyboardInterrupt as exc:
+        raise typer.Exit(130) from exc
+
+
+def setup(
+    ctx: typer.Context,
+    provider: Annotated[
+        Literal["hetzner", "gcp", "ssh"] | None, typer.Option("--provider", help="Host provider: hetzner, gcp or ssh (existing server).")
+    ] = None,
+    action: Annotated[
+        Literal["check", "create", "init"] | None,
+        typer.Option("--action", help="check prerequisites only, create a cloud host, or init an existing server."),
+    ] = None,
+    name: Annotated[str, typer.Option("--name", help="Host name to create or register.")] = "main",
+    ssh_key: Annotated[
+        Path | None, typer.Option("--ssh-key", help="Private SSH key. Default: ~/.ssh/id_ed25519, else ~/.ssh/offbox_ed25519.")
+    ] = None,
+    size: Annotated[str | None, typer.Option("--size", help="Cloud machine type for --action create.")] = None,
+    region: Annotated[str | None, typer.Option("--region", help="Cloud location or zone for --action create.")] = None,
+    target: Annotated[str | None, typer.Option("--target", help="USER@ADDRESS of the existing server for --action init.")] = None,
+    port: Annotated[int, typer.Option("--port", min=1, max=65535, help="SSH port of the existing server.")] = 22,
+    host_key_fingerprint: Annotated[
+        str | None, typer.Option("--host-key-fingerprint", help="Expected SHA256:... host key fingerprint for --action init.")
+    ] = None,
+    accept_host_key: Annotated[
+        bool, typer.Option("--accept-host-key", help="Trust the scanned host key without verification; prefer --host-key-fingerprint.")
+    ] = False,
+) -> None:
+    """Check prerequisites, install missing tools and explicitly create or register a host."""
+    from offbox.setup import SetupOptions
+    from offbox.setup import setup as run_setup
+
+    def ask(message: str, default: str) -> str:
+        return str(typer.prompt(message, default=default))
+
+    interactive = console.interactive()
+    run_setup(
+        Paths.discover(),
+        _runner(ctx),
+        SetupOptions(
+            provider=provider,
+            action=action,
+            name=name,
+            ssh_key=ssh_key,
+            size=size,
+            region=region,
+            target=target,
+            port=port,
+            accept_host_key=accept_host_key,
+            host_key_fingerprint=host_key_fingerprint,
+        ),
+        ask=ask if interactive else None,
+        confirm=typer.confirm if interactive else None,
+        offer=console.confirm if interactive else None,
+    )
+
+
+def uninstall(
+    ctx: typer.Context,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm without a prompt.")] = False,
+    abandon_cloud_hosts: Annotated[
+        bool, typer.Option("--abandon-cloud-hosts", help="Remove local records even though cloud hosts keep running and billing.")
+    ] = False,
+) -> None:
+    """Remove local offbox resources while retaining user configuration and remote hosts."""
+    run_uninstall(Paths.discover(), _runner(ctx), yes=yes, abandon_cloud_hosts=abandon_cloud_hosts)
+
+
+def register(app: typer.Typer) -> None:
+    app.command()(status)
+    app.command()(logs)
+    app.command()(setup)
+    app.command()(uninstall)

offbox/cli/ports.py

@@ -0,0 +1,44 @@
+from typing import Annotated
+
+import typer
+
+from offbox import console
+from offbox.errors import OffboxError
+from offbox.host import host_operation
+from offbox.paths import Paths
+from offbox.project import load_project
+from offbox.runner import SubprocessRunner
+from offbox.runtime import Runtime
+
+
+def ports(
+    ctx: typer.Context,
+    json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False,
+    swap: Annotated[
+        int | None,
+        typer.Option(
+            "--swap", min=1, max=65535, help="Give this worktree localhost:PORT for remote PORT, swapping with its current owner."
+        ),
+    ] = None,
+) -> None:
+    """Restore this worktree's port forwards and show its localhost mappings."""
+    runner: object = ctx.find_root().obj
+    if not isinstance(runner, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    paths = Paths.discover()
+    runtime = Runtime(paths, runner)
+    with runtime.using("offbox ports") as (work, _env, host):
+        config = load_project(paths, work.root)
+        with host_operation(paths, host.name, wait_timeout=120, clock=runtime.clock):
+            report = runtime.ports.restore(work, host, config.ports)
+        if swap is not None:
+            report = runtime.ports.swap(work, swap)
+    if json:
+        console.json_out(report)
+    else:
+        for forward in report.forwards:
+            console.output(f"localhost:{forward.local} → {forward.env}:{forward.remote}")
+
+
+def register(app: typer.Typer) -> None:
+    app.command()(ports)

offbox/config.py

@@ -0,0 +1,189 @@
+import os
+import re
+import stat
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, SecretStr, ValidationError, model_validator
+
+from offbox import DEFAULT_IMAGE
+from offbox.errors import PreconditionError
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+
+HOST_NAME = r"^[a-z][a-z0-9-]{0,31}$"
+_DURATION = re.compile(r"([1-9][0-9]{0,5})([mhd])")
+_DURATION_SECONDS = {"m": 60, "h": 3600, "d": 86400}
+
+
+def duration_seconds(value: str) -> int | None:
+    """Seconds for a duration such as 30m, 2h or 1d; None for off."""
+    if value == "off":
+        return None
+    match = _DURATION.fullmatch(value)
+    if match is None:
+        raise ValueError("use a duration such as 30m, 2h or 1d, or off")
+    return int(match[1]) * _DURATION_SECONDS[match[2]]
+
+
+class HostPreset(Model):
+    provider: str = "hetzner"
+    size: str | None = None
+    region: str | None = None
+    image: str | None = None
+    address: str | None = None
+    port: int = Field(default=22, ge=1, le=65535)
+    ssh_key: Path | None = None
+    auto: bool = False
+    idle: str = "2h"
+
+    @model_validator(mode="after")
+    def validate_lifecycle(self) -> Self:
+        duration_seconds(self.idle)
+        if self.auto and self.provider == "ssh":
+            raise ValueError("auto applies to cloud providers; existing SSH servers are never created or destroyed automatically")
+        return self
+
+
+class UserConfig(Model):
+    default_host: str | None = None
+    hosts: dict[str, HostPreset] = Field(default_factory=dict)
+    project: dict[str, dict[str, JsonValue]] = Field(default_factory=dict[str, dict[str, JsonValue]])
+
+
+class EnvConfig(Model):
+    host: str | None = Field(default=None, pattern=HOST_NAME)
+    image: str | None = None
+    dockerfile: Path | None = None
+    cpus: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+    memory: str | None = None
+    shm_size: str = "2g"
+
+    @model_validator(mode="after")
+    def validate_image(self) -> Self:
+        if self.image is not None and self.dockerfile is not None:
+            raise ValueError("env.image and env.dockerfile are mutually exclusive")
+        if self.image is None and self.dockerfile is None:
+            self.image = DEFAULT_IMAGE
+        return self
+
+    def resource_limits(self, host_cpus: int, host_memory: int) -> tuple[float, str]:
+        if host_cpus < 1 or host_memory < 1:
+            raise PreconditionError("Invalid host resource information", "Check the host CPU and memory information.")
+        return self.cpus if self.cpus is not None else float(max(1, host_cpus - 1)), self.memory or str(host_memory * 3 // 4)
+
+
+class InstallConfig(Model):
+    command: str | None = None
+    when: list[str] = Field(default_factory=list)
+
+
+class StackConfig(Model):
+    up: str | None = None
+    down: str | None = None
+
+    def commands(self, root: Path) -> tuple[str | None, str | None]:
+        compose = any(
+            (root / filename).is_file() for filename in ("compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml")
+        )
+        return self.up or ("docker compose up -d" if compose else None), self.down or ("docker compose down" if compose else None)
+
+
+class PortsConfig(Model):
+    forward: list[int] = Field(default_factory=list[int])
+    auto: bool = True
+
+    @model_validator(mode="after")
+    def validate_ports(self) -> Self:
+        if any(port < 1 or port > 65535 for port in self.forward):
+            raise ValueError("ports.forward entries must be between 1 and 65535")
+        return self
+
+
+class SyncConfig(Model):
+    ignore: list[str] = Field(default_factory=list)
+
+
+class ExecConfig(Model):
+    env: list[str] = Field(default_factory=list)
+
+
+class FilesConfig(Model):
+    copy_: list[str] = Field(default_factory=list, alias="copy")
+
+
+class GitConfig(Model):
+    mirror: bool = True
+    refs: list[str] = Field(default_factory=list)
+
+
+class ProjectConfig(Model):
+    env: EnvConfig = Field(default_factory=EnvConfig)
+    install: InstallConfig = Field(default_factory=InstallConfig)
+    stack: StackConfig = Field(default_factory=StackConfig)
+    ports: PortsConfig = Field(default_factory=PortsConfig)
+    sync: SyncConfig = Field(default_factory=SyncConfig)
+    exec: ExecConfig = Field(default_factory=ExecConfig)
+    files: FilesConfig = Field(default_factory=FilesConfig)
+    git: GitConfig = Field(default_factory=GitConfig)
+
+
+class HetznerCredentials(Model):
+    token: SecretStr | None = None
+
+
+class Credentials(Model):
+    hetzner: HetznerCredentials = Field(default_factory=HetznerCredentials)
+
+
+def load_config[T: BaseModel](path: Path, model: type[T]) -> T:
+    try:
+        with path.open("rb") as source:
+            return model.model_validate(tomllib.load(source))
+    except FileNotFoundError:
+        return model()
+    except ValidationError as exc:
+        locations = [".".join(str(part) for part in error["loc"]) or "<root>" for error in exc.errors(include_input=False)]
+        raise PreconditionError(f"Invalid configuration in {path}: {', '.join(locations)}", f"Correct these keys in {path}.") from exc
+    except (tomllib.TOMLDecodeError, UnicodeError, OSError) as exc:
+        raise PreconditionError(f"Cannot read configuration {path}", f"Fix the TOML syntax and permissions in {path}.") from exc
+
+
+def load_credentials(path: Path) -> Credentials:
+    try:
+        with path.open("rb") as source:
+            if stat.S_IMODE(os.fstat(source.fileno()).st_mode) & 0o177:
+                raise PreconditionError(f"Credentials file {path} is more permissive than 0600", f"chmod 600 {path}")
+            return Credentials.model_validate(tomllib.load(source))
+    except FileNotFoundError:
+        return Credentials()
+    except ValidationError as exc:
+        locations = [".".join(str(part) for part in error["loc"]) or "<root>" for error in exc.errors(include_input=False)]
+        raise PreconditionError(
+            f"Invalid credentials file {path}: {', '.join(locations)}", f"Correct {path}; keep permissions at 0600."
+        ) from exc
+    except (tomllib.TOMLDecodeError, UnicodeError, OSError) as exc:
+        raise PreconditionError(f"Invalid credentials file {path}", f"Correct {path}; keep permissions at 0600.") from exc
+
+
+def hetzner_token(path: Path, env: Mapping[str, str] | None = None) -> SecretStr:
+    values = os.environ if env is None else env
+    token = values.get("HCLOUD_TOKEN")
+    if token:
+        return SecretStr(token)
+    saved = load_credentials(path).hetzner.token
+    if saved is not None and saved.get_secret_value():
+        return saved
+    raise PreconditionError(
+        "Missing Hetzner credentials",
+        "Set HCLOUD_TOKEN or hetzner.token in credentials.toml (mode 0600); see https://github.com/o-avdieiev/offbox/blob/master/docs/installation.md#hetzner.",
+    )
+
+
+def default_host(user: UserConfig, state_default: str | None) -> str | None:
+    return state_default if state_default is not None else user.default_host