flaxcloud 0.4.0

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)

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.