forktex-cloud

Standalone Python SDK for the ForkTex Cloud platform.

forktex-cloud is the typed httpx client + manifest plumbing for the ForkTex Cloud control plane: project provisioning, server management, deployments, vault, manifest validation, and the docker-compose / Hetzner / Ansible bridge. It was the library behind the retired forktex cloud … CLI; today it is used directly from Python applications, the platform's own runner, and CI.

Install

pip install forktex-cloud

Requires Python ≥ 3.14 (requires-python = ">=3.14,<4.0").

Quick Start

Authenticated client

from forktex_cloud import Cloud, CloudContext

ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
with Cloud.from_context(ctx) as client:
    projects = client.list_projects()
    servers  = client.list_servers()
    health   = client.health()

Direct auth

from forktex_cloud import Cloud

# JWT bearer (user login)
with Cloud("https://cloud.forktex.com", access_token="eyJ...") as client:
    me = client.me()

# Org-scoped API key (CI/CD)
with Cloud(
    "https://cloud.forktex.com",
    account_key="ftx-...",
    org_id="00000000-0000-0000-0000-000000000001",
) as client:
    events = client.list_events(project_id="...")
    status = client.server_status("server-uuid")

Local dev (point at your make local stack)

client = Cloud(
    base_url="http://localhost:8000",
    account_key="ftx-dev-key-2026",
    org_id="<your-org-uuid>",
)

For integration tests or proxying through a mock/live transport, pass the
optional `transport=` argument to `Cloud(...)` and provide any `httpx`
transport implementation.

Trigger a deploy pipeline

# Preview what an apply WOULD do (read-only, no mutation):
plan = client.plan(project_dir=Path("./my-project"), env="production")
print(plan.manifest_diff)            # added / removed / changed paths
for role in plan.ansible_plan:
    print(f"  {role.role}: {role.changed} changed, {role.failed} failed")
    for d in role.diffs:
        print(f"    {d.task}: {d.before_header}")  # file-level diff hints

# Full apply (provision + bootstrap + deploy + DNS + SSL)
job = client.apply(project_dir=Path("./my-project"))      # reads forktex.json
print(job.job_id, job.deployment_id, job.status)

# Code push to an existing server (no re-provision)
job = client.deploy(server_id="...", service="api")    # Ansible deploy tag

# Tear down
job = client.destroy(keep_dns=True)                       # preserves DNS record

Manifest loading + validation

from forktex_cloud import Manifest, ManifestError

# Validates eagerly against the canonical Pydantic schema at construction
try:
    m = Manifest.load("forktex.json", env="production")
except ManifestError as e:
    print(f"Invalid manifest: {e}")
    raise

# Typed access to the cloud block (discriminated union over all 4 kinds)
print(m.cloud.kind)                     # "ProjectDeployment" | "StaticSite" | ...
print(m.cloud.metadata.name)
for svc in m.services_for_env(env="production"):
    print(svc.id, svc.type, svc.image)

# Wire format round-trips cleanly (model_dump → parse_cloud_block)
as_dict = m.cloud.model_dump(by_alias=True, exclude_none=True)

Secrets vault (server-side, org-scoped)

client.vault_set("POSTGRES_PASSWORD", "hunter2")
secret = client.vault_get("POSTGRES_PASSWORD")           # -> VaultGetResponse
keys   = client.vault_list()                             # -> list[str]
client.vault_delete("POSTGRES_PASSWORD")

What's in the package

All response models come from the OpenAPI codegen pipeline — one source of truth shared between the server and every consumer. No hand-written model drift.

Top-level re-exports

from forktex_cloud import (
    # Client
    Cloud, CloudAPIError,
    # Config
    CloudContext,
    # Manifest
    Manifest, ManifestError,
    # Response models (from OpenAPI codegen)
    ApiKeyCreated, ApiKeyRead,
    EnvironmentRead, EventRead,
    HealthRead, JobResponse, MeResponse,
    OrgRead, ProjectRead, ServerRead, UserRead,
    StatusResponse, TokenResponse, VaultGetResponse,
    WorkspaceRead,
)

Versioning

The SDK follows SemVer. The client's response models are generated from the server's OpenAPI spec at a fixed SPEC_VERSION + SPEC_HASH (inspectable at runtime via forktex_cloud.client.generated.SPEC_VERSION). When the server OpenAPI changes, the SDK is regenerated and released with a bumped version.

Repository

This SDK lives inside the forktex/cloud monorepo alongside the API server (api/) and React Native client (client/). The SDK package is independently versioned and published to PyPI.

• Docs: https://github.com/forktex/cloud/tree/master/docs
• Operations guide: operations.md
• Issues: https://github.com/forktex/cloud/issues

License

MIT — see LICENSE.