vxsdk

README

vxsdk — vxcloud / VxCloud SDK suite

Three first-class SDKs that share one wire contract:

Language	Package	Location	Install
Go	vxsdk-go	this directory	go get github.com/prodxcloud/vxcloud@latest
Python	vxsdk	./python	pip install vxsdk (or drop vxsdk.py in)
TypeScript	@vxcloud/sdk	./typescript	npm install @vxcloud/sdk

All three speak the same JSON wire contract, share the same auth model (X-API-Key + Bearer JWT with refresh-on-401), resolve the same per-tenant node, and expose the same resource modules. They are kept at parity with each other and with the vxcli command surface. No platform-side change is required to use any of them.

Status: preview. API surface stable across minor versions only after 1.0. Roadmap, milestones, and risk register live in BIG_PLAN.md and CHANGELOG.md.

Why this exists

vxcli already speaks the vxcloud API end-to-end, but every command rebuilds its own http.NewRequest, has its own timeout, and re-encodes auth headers inline. Other services (the gateway, future microservices, customer integrations) end up reinventing the same client layer. The SDK extracts that contract into one place per language:

• One HTTP client per Client, with retry/backoff and typed errors.
• One auth contract — Authorization: Bearer <jwt> and X-API-Key: xc_*, the same pair the FastAPI backend already accepts. No backend change required.
• Resource modules per domain (sessions, cicd, vxcomputer, …) modeled after the existing FastAPI / node routers.
• Reads ~/.vxcloud/credentials.json so anyone already logged in via vxcli can use the SDK without re-supplying credentials.

Quick start

Go

package main

import (
    "context"
    "fmt"
    vxsdk "github.com/prodxcloud/vxcloud"
    "github.com/prodxcloud/vxcloud/vxcomputer"
)

func main() {
    ctx := context.Background()
    c, err := vxsdk.LoadFromVxcli(ctx) // or vxsdk.New(ctx, vxsdk.WithAPIKey(...))
    if err != nil { panic(err) }

    pipelines, err := c.CICD().Pipelines().List(ctx)
    if err != nil { panic(err) }
    for _, p := range pipelines {
        fmt.Println(p.ID, p.Name, p.Repository)
    }

    // Control plane: run a governed agent objective on the node.
    res, err := c.VxComputer().Run(ctx, vxcomputer.RunInput{
        Objective: "Check disk usage and report",
        Channel:   "cloudshell",
    })
    if err != nil { panic(err) }
    fmt.Println(res["status"])
}

Python

import vxsdk

c = vxsdk.Client.load_from_vxcli()          # reads ~/.vxcloud/credentials.json
print(c.cicd.pipelines.list())

# Control plane
print(c.vxcomputer.run("Check disk usage and report", channel="cloudshell"))
print(c.workflow.list())

TypeScript

import { VxCloud } from '@vxcloud/sdk';

const c = await VxCloud.loadFromVxcli();
console.log(await c.cicd.pipelines.list());

// Control plane
console.log(await c.vxcomputer.run({ objective: 'Check disk usage', channel: 'cloudshell' }));
console.log(await c.workflow.list());

Resource modules

Every SDK exposes the same resource modules off the client. The control plane resources (vxcomputer, workflow, vxchrono, robotic) mirror the vxcli commands of the same name 1:1.

Module	Go	Python	TS	What it covers
auth	✓	✓	✓	API-key → JWT exchange, whoami, refresh-on-401
sessions	✓	✓	✓	Deploy/install sessions — list, show, apply, pull, delete
cicd	✓	✓	✓	Pipelines, builds, Git provider connections
install	✓	✓	✓	Run remote install scripts / docker-compose stacks over SSH
deploy	✓	✓	✓	Container + language-stack deploys to a VM
marketplace	✓	✓	✓	Agents, models, Terraform solutions
cloud	✓	✓	✓	Cloud provisioning — VM, S3, IAM, network, database, k8s, serverless
nodes	✓	✓	✓	Tenant-node management (Infinity control plane)
services	✓	✓	✓	Container/host lifecycle — start/stop/restart/remove, host ops
networks	✓	✓	✓	Network-diagnostic scripts (DNS, bandwidth, ports, audits)
agents	✓	✓	✓	AI agents — coding / devops / git / parallel / presets / tools
chat	✓	✓	✓	Multi-provider AI chat
observability	✓	✓	✓	Backups, migrations, resource synchronization
billing	✓	✓	✓	Multicloud cost / optimization reports
workspace	✓	✓	✓	/api/v2/setup/* — workspace + credential storage (incl. SSL certs)
metaldb	✓	✓	—	Self-managed PostgreSQL (MetalDB) — SSH test-connection + provision
agentcontrol	✓	✓	—	Fine-tuning, training, knowledge bases, datasets, server-side agents, GitHub import
vxcomputer	✓	✓	✓	Node-local policy-governed agent runtime (Plan→Act→Reflect)
workflow	✓	✓	✓	Visual DAG workflow orchestration (n8n-style)
vxchrono	✓	✓	✓	Autonomous goal executor & scheduler
robotic	✓	✓	✓	Robotic control cloud (robots, fleet, telemetry)

metaldb and agentcontrol are not yet in the TypeScript SDK — Go and Python have full coverage. The Python SDK also ships an async client (vxsdk_async.py, AsyncClient) covering the same modules.

Control Plane modules

These four modules target node-local control-plane services under /api/v2/* on the resolved tenant node. Each is at parity across the three SDKs and with the vxcli vxcomputer | workflow | vxchrono | robotic commands.

// VXCOMPUTER — governed agent loop
c.VxComputer().Info(ctx)
c.VxComputer().Classify(ctx, "rm -rf /tmp/x")
c.VxComputer().Run(ctx, vxcomputer.RunInput{Objective: "…", Channel: "cloudshell"})
c.VxComputer().ResolveApproval(ctx, vxcomputer.ApprovalInput{RunID: id, Command: cmd})
c.VxComputer().AuditVerify(ctx)

// Workflow — visual DAG engine
c.Workflow().List(ctx)
c.Workflow().Validate(ctx, definition)
c.Workflow().Execute(ctx, map[string]interface{}{"workflow_id": id})
c.Workflow().ListExecutions(ctx)
c.Workflow().CancelExecution(ctx, executionID)
c.Workflow().Export(ctx, definition, "yaml")

// VxChrono — autonomous goal scheduler
c.VxChrono().CreateGoal(ctx, goal)
c.VxChrono().Schedule(ctx, goalID, schedule)
c.VxChrono().LaunchRun(ctx, goalID, nil)
c.VxChrono().PauseRun(ctx, runID) // + ResumeRun / StopRun
c.VxChrono().DispatchScheduler(ctx)

// Robotic — robotic control cloud
c.Robotic().ListRobots(ctx)
c.Robotic().RegisterRobot(ctx, spec)
c.Robotic().SendCommand(ctx, robotID, payload)
c.Robotic().Telemetry(ctx, robotID, frame)
c.Robotic().EmergencyStop(ctx, robotID)
c.Robotic().FleetCommand(ctx, payload)

Python and TypeScript expose the same operations with idiomatic naming (c.vxcomputer.run(...), await c.workflow.list(), …).

Core resource examples (Go)

// list pipelines
pipelines, _ := c.CICD().Pipelines().List(ctx)

// trigger a build
build, _ := c.CICD().Pipelines().Trigger(ctx, pipelineID, "main")

// install a custom script via SSH+SCP
res, _ := c.Install().Script(ctx, install.ScriptOpts{
    SSH:        install.SSH{Host: "54.197.71.181", User: "ubuntu", KeyPairName: "AWSPRODKEY1.PEM"},
    ScriptName: "bootstrap.sh",
    Script:     scriptBytes,
    Args:       []string{"--tier=prod"},
})

// deploy a single Docker container
res, _ := c.Deploy().Container(ctx, deploy.ContainerOpts{
    SSH:           deploy.SSH{Host: ip, User: "ubuntu", KeyPairName: keyName},
    Image:         "grafana/grafana:latest",
    Name:          "grafana",
    Ports:         []string{"3000:3000"},
    RestartPolicy: "unless-stopped",
})

// deploy a language stack from a public git repo
res, _ := c.Deploy().Stack(ctx, deploy.StackGolang, deploy.StackOpts{
    SSH:         deploy.SSH{Host: ip, User: "ubuntu", KeyPairName: keyName},
    RepoURL:     "https://github.com/joelwembo/va-sample-golang.git",
    Branch:      "main",
    GitProvider: "github",
    AppName:     "va-sample-golang",
    HTTPPort:    "80",
    GoVersion:   "1.22",
})

Domains, DNS & HTTPS

DNS records and CDN distributions are provisioned through c.Cloud() (the same /api/v2/tenant/provision/* surface vxcli deploy --service route53|cname|cloudfront uses). HTTPS for a deployed app is requested at deploy time — the deploy container/stack options carry EnableSSL, Domain, and SSLEmail fields, mirroring the vxcli deploy --enable-ssl --domain --ssl-email flags. To store an externally-issued certificate as a workspace credential, use the workspace module (/api/v2/setup/ssl-certificate-credentials), which matches vxcli configure setup ssl.

Go module layout

services/sdk/
├── go.mod                 sub-module: github.com/prodxcloud/vxcloud
├── doc.go                 package overview
├── client.go              vxsdk.New, vxsdk.LoadFromVxcli, vxsdk.Authenticate
├── options.go             WithAPIKey, WithJWT, WithInfinityURL, WithNodeURL, …
├── auth/                  APIKey, Token, User, ExchangeResponse, Exchange()
├── transport/             one *http.Client; JSON + multipart; retry; auto-refresh on 401
├── errors/                typed error hierarchy; IsRetryable, FromHTTP
├── sessions/              c.Sessions()
├── cicd/                  c.CICD().Pipelines() / .Builds()
├── install/               c.Install().Script() / .Compose()
├── deploy/                c.Deploy().Container() / .Stack()
├── marketplace/           c.Marketplace().Agents() / .Models() / .Solutions()
├── cloud/                 c.Cloud().S3/IAM/VM/Network/Database/Kubernetes/Serverless()
├── nodes/                 c.Nodes() (Infinity control plane)
├── services/              c.Services() — container + host lifecycle
├── networks/              c.Networks() — diagnostic scripts
├── agents/                c.Agents() — AI agents
├── chat/                  c.Chat() — multi-provider AI chat
├── observability/         c.Observability() — backups / migrations / sync
├── billing/               c.Billing() — multicloud cost
├── workspace/             c.Workspace() — /api/v2/setup/* credentials
├── metaldb/               c.MetalDB() — self-managed PostgreSQL over SSH
├── agentcontrol/          c.AgentControl() — fine-tuning / training / datasets
├── vxcomputer/            c.VxComputer() — governed agent runtime
├── workflow/              c.Workflow() — visual workflow engine
├── vxchrono/              c.VxChrono() — goal scheduler
├── robotic/               c.Robotic() — robotic control cloud
├── vxsdktest/             stub HTTP server for SDK consumers' unit tests
├── internal/cred/         read ~/.vxcloud/credentials.json
└── examples/              basic / install_script / marketplace

Design contracts (what stays stable across versions)

Contract	Promise
Auth headers	The SDK only ever sets Authorization: Bearer and X-API-Key. No custom headers, no query-param tokens.
Errors	Every method returns one of the typed errors in errors/. New error categories may be added but never removed. Use errors.As to branch.
Retries	NetworkError, ServerError, RateLimitError are retried with exponential backoff up to MaxRetries (default 3). All others surface immediately.
Wire format	Struct tags use json:"snake_case" to match the FastAPI wire format verbatim. Go callers see normal CamelCase identifiers.
Control-plane shapes	Control-plane modules return the decoded JSON object as-is (map[string]interface{} / dict / Record<string,unknown>) — their response shapes are dynamic and intentionally not over-modeled.
Tracing	Every request carries a fresh vx-request-id header. A future WithTracer(...) option will hook OpenTelemetry; the existing header is forward-compatible.
Versioning	Sub-module tagged independently as services/sdk/v0.1.0-preview etc. v1.0 will guarantee API stability across minor releases.

Verified live

Core endpoints exercised against node1.vxcloud.io during preview:

Module	Method	Result
cicd.Pipelines.List	GET /api/v2/cicd/pipelines	returned 4 pipelines
install.Script	POST /api/v2/tenant/install/script (multipart)	exit_code=0, stdout returned
marketplace.Agents.List	GET /api/v2/marketplace/agents	returned 7 agents
marketplace.Solutions.List	GET /api/v2/marketplace/templates	returned 30 solutions
auth.Exchange (auto-refresh)	POST /api/v1/auth/developer/keys/login	new JWT pair returned

go test ./vxsdktest/... exercises happy path, auto-refresh on 401, and typed *AuthError against an in-process stub server.

The control-plane modules (vxcomputer, workflow, vxchrono, robotic — all three SDKs) and the Go metaldb / agentcontrol modules are newly added in this release. They are wired to the same transport/auth/error stack and compile/typecheck/go vet clean, but have not yet been exercised against a live node — treat them as preview until added to the table above.

Tagging the SDK as a public Go module

The SDK lives at services/sdk/ but ships as its own Go module (go.mod already in place).

# 1. Replace the placeholder module path with your actual GitHub org.
sed -i 's|github.com/prodxcloud/vxcloud|github.com/<your-org>/<your-repo>|g' \
    services/sdk/go.mod services/sdk/**/*.go

# 2. Commit + tag with the sub-module prefix.
git add services/sdk
git commit -m "sdk: v0.1.0-preview"
git tag services/sdk/v0.1.0-preview
git push origin services/sdk/v0.1.0-preview

# 3. From any other Go module:
go get github.com/<your-org>/<your-repo>/services/sdk@v0.1.0-preview

Status

Preview. Subject to change. Not yet linked to the frontend or the API gateway. Production code should pin to a specific commit until v0.1.0 is tagged.

Documentation

Overview

Package vxsdk is the official Go SDK for the vxcloud platform.

It provides a typed, ergonomic client over the FastAPI control plane at api.vxcloud.io (Infinity) and per-tenant nodes (e.g. node1.vxcloud.io).

The SDK is preview / research quality. It is additive to existing tooling — vxcli, the API gateway, and the FastAPI backend are not modified by this package. External Go services may import it via:

go get github.com/prodxcloud/vxcloud@latest

Basic usage

c, err := vxsdk.New(ctx,
    vxsdk.WithAPIKey("xc_dev_..."),
    vxsdk.WithUsername("joelwembo"),
)
if err != nil { return err }

pipelines, err := c.CICD().Pipelines().List(ctx)

Auth precedence

If WithAPIKey is provided, the SDK exchanges it for a JWT on first call and caches both. Subsequent requests carry both Authorization: Bearer and X-API-Key headers — the same pattern vxcli uses today, which keeps the SDK compatible with all existing FastAPI auth dependencies without requiring any backend change.

Index

• Constants
• type Client
  • func LoadFromVxcli(ctx context.Context, opts ...Option) (*Client, error)
  • func New(_ context.Context, opts ...Option) (*Client, error)
  • func (c *Client) AgentControl() *agentcontrol.Client
  • func (c *Client) Agents() *agents.Client
  • func (c *Client) Authenticate(ctx context.Context) error
  • func (c *Client) Billing() *billing.Client
  • func (c *Client) CICD() *cicd.Client
  • func (c *Client) Chat() *chat.Client
  • func (c *Client) Cloud() *cloud.Client
  • func (c *Client) Deploy() *deploy.Client
  • func (c *Client) InfinityURL() string
  • func (c *Client) Install() *install.Client
  • func (c *Client) Marketplace() *marketplace.Client
  • func (c *Client) MetalDB() *metaldb.Client
  • func (c *Client) Networks() *networks.Client
  • func (c *Client) NodeURL() string
  • func (c *Client) Nodes() *nodes.Client
  • func (c *Client) Observability() *observability.Client
  • func (c *Client) Robotic() *robotic.Client
  • func (c *Client) Services() *services.Client
  • func (c *Client) Sessions() *sessions.Client
  • func (c *Client) TenantID() string
  • func (c *Client) VxChrono() *vxchrono.Client
  • func (c *Client) VxComputer() *vxcomputer.Client
  • func (c *Client) Whoami() auth.User
  • func (c *Client) Workflow() *workflow.Client
  • func (c *Client) Workspace() *workspace.Client
• type Option
  • func WithAPIKey(apiKey string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithInfinityURL(u string) Option
  • func WithJWT(access, refresh string) Option
  • func WithNodeURL(u string) Option
  • func WithTenantID(id string) Option
  • func WithTimeout(d time.Duration) Option
  • func WithUserAgent(ua string) Option
  • func WithUsername(u string) Option

Constants

const Version = "0.1.0-preview"

Version is the SDK version string. Bumped manually on tag.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the entry point of the SDK. Construct one with New, hold it for the life of your process, and acquire resource modules with the methods Sessions(), CICD(), etc.

Client is safe for concurrent use by multiple goroutines.

func LoadFromVxcli

func LoadFromVxcli(ctx context.Context, opts ...Option) (*Client, error)

LoadFromVxcli is a convenience constructor that reads ~/.vxcloud/credentials.json (the file `vxcli auth login` writes) and returns a Client using the same identity. opts may add overrides.

func New

func New(_ context.Context, opts ...Option) (*Client, error)

New constructs a Client. At least one of WithAPIKey or WithJWT must be supplied — or LoadFromVxcli (which reads ~/.vxcloud/credentials.json).

The constructor does not perform a network round-trip. The first method call on a resource module triggers credential exchange if needed.

func (*Client) AgentControl

func (c *Client) AgentControl() *agentcontrol.Client

AgentControl returns the AgentControl module — fine-tuning, training, knowledge bases, datasets, server-side agents, and GitHub import.

Every AgentControl call sends an X-Tenant-ID header. The tenant id is taken from WithTenantID / LoadFromVxcli; override per use by setting the returned client's TenantID field.

func (*Client) Agents

func (c *Client) Agents() *agents.Client

Agents returns the AI-agent resource module (coding/devops/git/ parallel/presets/tool/tools).

func (*Client) Authenticate

func (c *Client) Authenticate(ctx context.Context) error

Authenticate proactively exchanges the configured API key for a fresh JWT pair. Optional — the SDK refreshes automatically on the first 401 — but useful for fail-fast startup checks.

func (*Client) Billing

func (c *Client) Billing() *billing.Client

Billing returns the multicloud cost / optimization module.

func (*Client) CICD

func (c *Client) CICD() *cicd.Client

CICD returns the CI/CD resource module.

func (*Client) Chat

func (c *Client) Chat() *chat.Client

Chat returns the multi-provider AI chat module.

func (*Client) Cloud

func (c *Client) Cloud() *cloud.Client

Cloud returns the cloud-provisioning resource module (S3, IAM, VM, …).

func (*Client) Deploy

func (c *Client) Deploy() *deploy.Client

Deploy returns the container/stack deploy resource module.

func (*Client) InfinityURL

func (c *Client) InfinityURL() string

InfinityURL returns the control-plane base URL the Client is targeting.

func (*Client) Install

func (c *Client) Install() *install.Client

Install returns the script/compose installer resource module.

func (*Client) Marketplace

func (c *Client) Marketplace() *marketplace.Client

Marketplace returns the agents/models/solutions resource module.

func (*Client) MetalDB

func (c *Client) MetalDB() *metaldb.Client

MetalDB returns the MetalDB module — self-managed PostgreSQL provisioned over SSH onto a customer VM (test-connection + provision).

func (*Client) Networks

func (c *Client) Networks() *networks.Client

Networks returns the network-diagnostic resource module — list and remote-execute the embedded scripts (DNS, bandwidth, port checks, security audits).

func (*Client) NodeURL

func (c *Client) NodeURL() string

NodeURL returns the per-tenant node base URL.

func (*Client) Nodes

func (c *Client) Nodes() *nodes.Client

Nodes returns the tenant-node management resource module.

Note: nodes endpoints live on the Infinity control plane (not on a per-tenant node), so the InfinityURL is used.

func (*Client) Observability

func (c *Client) Observability() *observability.Client

Observability returns the backups + migrations + sync module.

func (*Client) Robotic

func (c *Client) Robotic() *robotic.Client

Robotic returns the Robotic control-cloud module — register robots, send commands, push telemetry, request plans, issue fleet commands.

func (*Client) Services

func (c *Client) Services() *services.Client

Services returns the lifecycle plane: start/stop/restart/remove a container, plus host-level operations under c.Services().VM().

Mirrors the `vxcli services` CLI surface.

func (*Client) Sessions

func (c *Client) Sessions() *sessions.Client

Sessions returns the deployment-sessions resource module.

func (*Client) TenantID

func (c *Client) TenantID() string

TenantID returns the tenant id used for the agentcontrol surface. Empty unless set via WithTenantID or loaded by LoadFromVxcli.

func (*Client) VxChrono

func (c *Client) VxChrono() *vxchrono.Client

VxChrono returns the VxChrono module — the autonomous goal executor and scheduler (goals, cron/interval schedules, run lifecycle).

func (*Client) VxComputer

func (c *Client) VxComputer() *vxcomputer.Client

VxComputer returns the VXCOMPUTER control-plane module — the node-local policy-governed agent runtime (Plan→Act→Reflect loop, risk policy, signed approvals, hash-chained audit ledger).

func (*Client) Whoami

func (c *Client) Whoami() auth.User

Whoami returns the authenticated principal. Useful for logging / display.

func (*Client) Workflow

func (c *Client) Workflow() *workflow.Client

Workflow returns the Workflow orchestration module — the n8n-style visual workflow engine (definitions, validation, execution, exports).

func (*Client) Workspace

func (c *Client) Workspace() *workspace.Client

Workspace returns the /api/v2/setup/* surface — workspace + organization lifecycle, cloud-provider credentials, AI-provider credentials, API tokens, Git/payment/SMTP/SSL/OAuth/OKTA credential storage.

type Option

type Option func(*config)

Option configures a Client. Use WithAPIKey, WithJWT, WithBaseURL, etc.

func WithAPIKey

func WithAPIKey(apiKey string) Option

WithAPIKey authenticates the client using a developer API key ("xc_dev_*", "xc_test_*", or "xc_live_*"). The key is exchanged for a short-lived JWT on first call and cached for the lifetime of the Client.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client. Use this to inject a transport with mTLS, custom proxies, or test fakes. The SDK still applies its own retry/timeout policy on top.

func WithInfinityURL

func WithInfinityURL(u string) Option

WithInfinityURL overrides the control-plane base URL (default https://api.vxcloud.io).

func WithJWT

func WithJWT(access, refresh string) Option

WithJWT authenticates with an existing JWT pair. Skips the API key exchange.

func WithNodeURL

func WithNodeURL(u string) Option

WithNodeURL overrides the tenant-node base URL. If unset, it is resolved from the API key exchange response (one round trip on first call).

func WithTenantID

func WithTenantID(id string) Option

WithTenantID pins the tenant id used for the agentcontrol surface (the X-Tenant-ID header). LoadFromVxcli populates this automatically from credentials.json when present.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout (default 30s).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header (default "vxsdk-go/<version>").

func WithUsername

func WithUsername(u string) Option

WithUsername pins the workspace username. If unset, the SDK derives it from the API key exchange response.