SDK overview¶

Use the HomeCloud SDK from your applications, workers, and CI jobs. Unlike the console, the SDK is built for automation: Access Keys, no interactive MFA on each request.

Language	Package	Docs
Python	`homecloud-sdk` (`import homecloud`)	Python SDK
Node.js	`@homecloud-platform/sdk`	Node.js SDK
Go	`github.com/HomeCloudLab/homecloud-sdk/go`	Go SDK
Java	`com.homecloudlab:homecloud-sdk`	Java SDK

All four languages target the same HomeCloud capabilities. Prefer the language your service already uses.

Auth model¶

Who	How	MFA
SDK / automation	Access Key ID + Secret (SigV1)	Never on data-plane requests
Humans / CLI login helpers	Username/password → JWT	At login / step-up only

Create keys in the console: Access Keys.

What you can call¶

Area	Typical methods	Auth
Object Storage (`so`)	upload, download, sync, list, delete, head, presign	Access Key
Queues (`mq`)	send, receive, delete, purge, DLQ	Access Key
Functions	list, invoke, url, logs	Mixed (see language pages)
Mail	mailboxes, messages, get, attachment	Access Key / session
Image Registry (`ir`)	list/create repos, usage	Session / key as documented
Secrets	list (JWT), getValue / putValue	Access Key for values
Management helpers	`so.list_buckets` / `create_bucket` / `delete_bucket`, `queues.list` / `get`	Access Key SigV1 (preferred); Console JWT fallback
Tasks + Diagrams	search/create/assign/comment/archive; diagrams list/get/create/update	User JWT or user-bound Access Key
Other console helpers	`apps.list`, `accounts.*`, IR create, Functions management	Console JWT (for now)

Minimal examples¶

PythonNode.jsGoJava

from homecloud import HomeCloud

client = HomeCloud.from_env()
client.so.upload("docs", "./a.txt", key="a.txt")
client.mq.send("orders", {"id": 1})

const { HomeCloud } = require("@homecloud-platform/sdk");

const client = HomeCloud.fromEnv();
await client.so.putJson("docs", "a.json", { ok: true });

client, _ := homecloud.FromEnv()
_, _ = client.SO.PutJSON(ctx, "docs", "a.json", map[string]any{"ok": true})

HomeCloud client = HomeCloud.fromEnv();
client.so().putJson("docs", "a.json", Map.of("ok", true));

Next¶

Create an Access Key
Follow Python, Node.js, Go, or Java
For shell scripts, you may prefer the CLI instead
To provision account resources from CI, use Terraform (not the SDK)