The official Python client for the Codesphere API.
uv add codesphereEvery option can be passed directly to the constructor:
from codesphere import CodesphereSDK
sdk = CodesphereSDK(token="your-api-token")
# or, e.g. against a different deployment:
sdk = CodesphereSDK(token="your-api-token", base_url="https://my-instance.example.com/api")Alternatively, configure via environment variables (or a .env file in your
project root). Explicit constructor arguments always win over the environment:
| Variable | Description | Default |
|---|---|---|
CS_TOKEN |
API token (required) | – |
CS_BASE_URL |
API base URL | https://codesphere.com/api |
If no token is provided at all, CodesphereSDK() raises an
AuthenticationError at construction (importing the package never requires
any environment variable).
Transient failures are retried automatically (2 retries by default).
Requests using an idempotent method (GET, HEAD, PUT, DELETE) are
retried on 429, 502, 503, and 504 responses as well as on
connect/timeout errors. The delay honors the server's Retry-After header
(seconds or HTTP-date) when present, otherwise exponential backoff with
jitter (backoff_factor * 2**attempt).
Tune or disable the behavior with a RetryConfig:
from codesphere import CodesphereSDK, RetryConfig
sdk = CodesphereSDK(
token="your-api-token",
retry=RetryConfig(max_retries=0), # disable retries entirely
)POST is never retried unless you add it to retry_methods explicitly
(only do this if your endpoints tolerate duplicate submissions):
RetryConfig(max_retries=3, retry_methods=frozenset({"GET", "POST"}))Platform instances enable different features. Inspect them via sdk.flags:
snapshot = await sdk.flags.get() # fetched once, then cached
if await sdk.flags.is_enabled("workspace-ssh"):
...
await sdk.flags.refresh() # re-fetch after platform changesSDK features that depend on a platform flag raise FeatureNotEnabledError
(or FeatureNotAvailableError if the instance doesn't have the feature at
all) before sending any request when the flag is off.
import asyncio
from codesphere import CodesphereSDK
async def main():
async with CodesphereSDK() as sdk:
teams = await sdk.teams.list()
for team in teams:
print(f"{team.name} (ID: {team.id})")
asyncio.run(main())The same API is available without async/await — ideal for scripts and
tools that don't run an event loop:
from codesphere.sync import CodesphereSDK
with CodesphereSDK() as sdk:
teams = sdk.teams.list()
for team in teams:
print(f"{team.name} (ID: {team.id})")Both flavors share the same request/response models, configuration, and
error types; only the entities with API methods (Workspace, Team, …)
exist per flavor.
teams = await sdk.teams.list()
team = await sdk.teams.get(team_id=123)
await team.delete()workspaces = await sdk.workspaces.list(team_id=123)
workspace = await sdk.workspaces.get(workspace_id=456)
result = await workspace.execute_command("ls -la")
print(result.output)
await workspace.env_vars.set([{"name": "API_KEY", "value": "secret"}])
env_vars = await workspace.env_vars.get()team = await sdk.teams.get(team_id=123)
domains = await team.domains.list()
domain = await team.domains.create(name="api.example.com")datacenters = await sdk.metadata.list_datacenters()
plans = await sdk.metadata.list_plans()
images = await sdk.metadata.list_images()git clone https://github.com/Datata1/codesphere-python.git
cd codesphere-python
uv sync --all-extras
uv run pytestMIT – see LICENSE for details.