flaxcloud 0.4.1

Python SDK and CLI for Flax Cloud: isolated cloud sandboxes.

flaxcloud - Python SDK & CLI for Flax Cloud

Programmatic access to Flax Cloud isolated sandboxes: create them, run commands, move files, preview servers, and wire them into agents/automation.

Install

pip install flaxcloud

Authenticate

Get an API key from the dashboard, then either set an environment variable or log in with the CLI (which stores it in ~/.config/flax/config.json):

export FLAX_API_KEY=flax_live_...
# or
flax login

SDK

from flaxcloud import FlaxClient

flax = FlaxClient()  # reads FLAX_API_KEY

# create_sandbox returns a handle with methods; use it as a context manager to auto-destroy
with flax.create_sandbox(template="python") as sb:
    out = sb.run("python3 -c 'print(6*7)'")
    print(out.stdout)          # "42\n"

    sb.upload("/workspace/app.py", "print('hello')\n")
    print(sb.run("python3 app.py").stdout)

    # long-running server + a shareable preview link
    sb.set_startup("python3 -m http.server 8000 --bind 0.0.0.0")
    sb.run_startup()
    print(sb.create_preview_link(8000).url)

Background commands:

sb = flax.create_sandbox(template="node")
job = sb.run("npm install", background=True)
done = sb.wait(job, timeout=600)
print(done.status, done.exit_code)

Environment variables, code execution, git, and filesystem helpers:

sb = flax.create_sandbox(template="python", env={"API_BASE": "https://example.com"})
sb.run("printenv TOKEN", env={"TOKEN": "secret"})        # per-command override
sb.code_run("print(6*7)", language="python")             # also node/bash/ruby
sb.git.clone("https://github.com/me/repo.git", "/workspace/repo")
sb.mkdir("/workspace/out"); sb.find("/workspace", name="*.py")

Stateful sessions - working directory and exported env persist across commands:

with sb.create_session() as s:        # auto-deletes on exit
    s.run("cd /workspace && export TOKEN=abc")
    print(s.run("pwd").stdout)         # /workspace
    print(s.run("echo $TOKEN").stdout) # abc

Streaming - live combined stdout/stderr as the command runs:

stream = sb.run_stream("for i in 1 2 3; do echo $i; sleep 1; done")
for chunk in stream:
    print(chunk, end="", flush=True)
print("exit:", stream.exit_code)

Custom images - register any public registry image, then create sandboxes from it:

tpl = flax.create_template("my-python", image="python:3.12-slim")  # waits until ready
sb = flax.create_sandbox(template="my-python")
print(sb.run("python3 --version").stdout)

You can also build a custom image from a Dockerfile (flax.create_template(..., dockerfile=...), streamed with flax.build_logs(id)), or describe it declaratively with FlaxImage and let the SDK generate the Dockerfile for you. The declarative builder uses the same Dockerfile build flow under the hood, so build status, logs, and wait behave identically:

from flaxcloud import FlaxImage

image = (
    FlaxImage.python("3.12")
    .apt_install(["git", "ffmpeg"])
    .pip_install(["requests", "beautifulsoup4"])
    .env({"PYTHONUNBUFFERED": "1"})
    .workdir("/workspace")
)

# Inspect the generated Dockerfile if you want:
print(image.to_dockerfile())

template = flax.create_template_from_image_definition("scraper-agent", image, wait=True)
sb = flax.create_sandbox(template="scraper-agent")

FlaxImage constructors: base(image), python(version), node(version), debian_slim(). Steps (chainable): apt_install, pip_install, npm_install, run, env, workdir, copy_file, copy_dir. Each package/argument is single-quoted and validated, so version specifiers like "requests>=2,<3" are safe; use .run(...) for anything custom. Note: copy_file/copy_dir need a local build context, which the hosted builder does not accept yet, so templates that use them can't be built remotely for now (use .run(...) to fetch files instead).

Async client:

import asyncio
from flaxcloud import AsyncFlaxClient

async def main():
    async with AsyncFlaxClient() as flax:
        async with await flax.create_sandbox(template="python") as sb:
            print((await sb.run("echo hi")).stdout)

asyncio.run(main())

Errors are typed (FlaxAuthError, FlaxNotFoundError, FlaxQuotaError, …), all subclasses of FlaxError. The client retries transient failures, sends a versioned User-Agent, and ships type hints (py.typed).

CLI

flax login
flax sandbox create --template python --startup "python3 -m http.server 8000 --bind 0.0.0.0"
flax sandbox ls
flax run sbx_abc123 "python3 -c 'print(6*7)'"
flax run sbx_abc123 "make build" --stream         # stream output live
flax session create sbx_abc123                     # cwd/env persist across exec
flax session exec ses_xyz "cd src && export E=1"
flax cp ./app.py sbx_abc123:/workspace/app.py
flax ls sbx_abc123 /workspace
flax preview sbx_abc123 8000
flax sandbox rm sbx_abc123

flax --help lists every command.