Go 1.22+ · v0.20260817.0

Go SDK

Idiomatic Go client. One *http.Client per Client, retry/backoff, single-flight refresh on 401, full interface coverage for all platform endpoints.

19 modules — every method shipped in v0.20260817.0 is documented below with a runnable example.

Go SDK

Go 1.22+v0.20260817.0 · 19 modules

Idiomatic Go client. One *http.Client per Client, retry/backoff, single-flight refresh on 401, full interface coverage for all platform endpoints.

Install

install · gobash

go get github.com/prodxcloud/vxcloud@latest

Quickstart

main.gogo

package main
 
import (
    "context"
    "fmt"
    vxsdk "github.com/prodxcloud/vxcloud"
)
 
import (
    "github.com/prodxcloud/vxcloud/deploy"
    "github.com/prodxcloud/vxcloud/install"
)
 
func main() {
    ctx := context.Background()
    c, err := vxsdk.LoadFromVxcli(ctx) // or vxsdk.New(ctx, vxsdk.WithAPIKey(...))
    if err != nil { panic(err) }
 
    pipelines, _ := c.CICD().Pipelines().List(ctx)
    for _, p := range pipelines {
        fmt.Println(p.ID, p.Name)
    }
 
    // Single-call HTTPS deploy: container + nginx + Let's Encrypt cert.
    // Requires grafana.example.com A record -> 13.216.243.13 already set.
    sess, _ := c.Deploy().Container(ctx, deploy.ContainerOpts{
        SSH: install.SSH{
            Host: "13.216.243.13", User: "ubuntu",
            KeyPairName: "AWSPRODKEY1",     // must be in Vault
        },
        Name:      "grafana",
        Image:     "grafana/grafana:latest",
        Ports:     []string{"3000:3000"},
        EnableSSL: true,
        Domain:    "grafana.example.com",
        SSLEmail:  "[email protected]",
    })
    fmt.Println(sess.SessionID, sess.AccessURL)
}

Modules

Client construction & authentication — 2 examples
sessions — 1 example
deploy (container + 14 stacks) — 5 examples
install (script / compose) — 1 example
services (lifecycle + host ops) — 2 examples
cicd — 1 example
marketplace — 1 example
cloud — 2 examples
agentcontrol (full /api/v2/agentcontrol/* surface — 22 sub-resources) — 6 examples
salesshift (tracked email + the leads pool) — 5 examples
networks — 1 example
agents (AI orchestration) — 1 example
chat (multi-provider AI) — 2 examples
observability — 1 example
billing — 1 example
workspace setup — 2 examples
nodes (list / register self-hosted / update / delete) — 4 examples
errors — 1 example
Production notes & known issues — 4 examples

Client construction & authentication

Two constructors — explicit options or load from `~/.vxcloud/credentials.json`. Exchange happens lazily; `Authenticate()` runs it eagerly for fail-fast.

1c, err := vxsdk.New(ctx,
2    vxsdk.WithAPIKey("xc_live_…"),
3    vxsdk.WithUsername("your-username"),
4    // optional:
5    // vxsdk.WithVxCloudURL("https://api.vxcloud.io"),
6    // vxsdk.WithNodeURL("https://node1.vxcloud.io"),
7)
8if err != nil { panic(err) }
9fmt.Println(c.Whoami().Username)

2 examples

vxsdk

sessions

Full session CRUD on the active node — list, inspect, replay (apply), fetch artifacts (pull), tear down.

1import "github.com/prodxcloud/vxcloud/sessions"
2 
3// List recent sessions
4list, err := c.Sessions().List(ctx)
5if err != nil { panic(err) }
6for _, s := range list { fmt.Println(s.ID, s.Status) }
7 
8// Inspect one
9detail, _ := c.Sessions().Show(ctx, "adc2d5c4-…")
10fmt.Println(detail["status"])
11 
12// Replay a planned deploy (previous run had --dry-run)
13c.Sessions().Apply(ctx, sessions.ApplyInput{SessionID: "adc2d5c4-…"})
14 
15// Fetch terraform state + artifacts
16artifacts, _ := c.Sessions().Pull(ctx, sessions.PullInput{SessionID: "adc2d5c4-…"})
17 
18// Simple tear down (no force)
19c.Sessions().Delete(ctx, "adc2d5c4-…")
20 
21// Force-delete variant (skips dependency checks server-side)
22c.Sessions().DeleteWith(ctx, sessions.DeleteInput{
23    SessionID: "adc2d5c4-…",
24    Force:     true,
25})

1 example

vxsdk

deploy (container + 14 stacks)

Deploy any Docker image (`Deploy().Container`) or any of the 14 supported stacks (`Deploy().Stack(kind, opts)`). Single-command HTTPS via `EnableSSL`/`Domain`/`SSLEmail` — host nginx + certbot for `Container`, shared Traefik for `Stack`.

1import (
2    "github.com/prodxcloud/vxcloud/deploy"
3    "github.com/prodxcloud/vxcloud/install"
4)
5 
6sess, err := c.Deploy().Container(ctx, deploy.ContainerOpts{
7    SSH: install.SSH{
8        Host:        "13.216.243.13",
9        User:        "ubuntu",
10        KeyPairName: "AWSPRODKEY1",   // must be in Vault
11    },
12    Name:      "grafana",
13    Image:     "grafana/grafana:latest",
14    Ports:     []string{"3000:3000"},
15    Env:       []string{"GF_SECURITY_ADMIN_PASSWORD=changeme"},
16    EnableSSL: true,
17    Domain:    "grafana.example.com",
18    SSLEmail:  "[email protected]",
19})
20if err != nil { panic(err) }
21fmt.Println(sess.SessionID, sess.AccessURL)

5 examples

vxsdk

install (script / compose)

Apply a custom shell installer or a docker-compose.yml on a remote VM.

1script, _ := os.ReadFile("./my-installer.sh")
2res, err := c.Install().Script(ctx, install.ScriptOpts{
3    Script:     script,
4    ScriptName: "my-installer.sh",
5    Args:       []string{"--version=2.1"},
6    SSH: install.SSH{
7        Host: "h", User: "ubuntu", KeyPairName: "AWSPRODKEY1.PEM",
8    },
9})
10fmt.Println(res.SessionID)
11 
12compose, _ := os.ReadFile("./docker-compose.yml")
13envFile, _ := os.ReadFile("./.env")
14c.Install().Compose(ctx, install.ComposeOpts{
15    Compose: compose, EnvFile: envFile, Stack: "myapi",
16    SSH: install.SSH{Host: "h", User: "ubuntu", KeyPairName: "AWSPRODKEY1.PEM"},
17})

1 example

vxsdk

services (lifecycle + host ops)

Start / stop / restart / remove / status of a Docker container, plus host-level operations under `Services().VM()`.

1import "github.com/prodxcloud/vxcloud/services"
2 
3ssh := services.SSH{
4    Host: "203.0.113.24", User: "ubuntu",
5    KeyPairName: "AWSPRODKEY1.PEM",
6}
7 
8list, _    := c.Services().List(ctx, ssh)
9status, _  := c.Services().Status(ctx, ssh, "studio-backend")
10 
11c.Services().Start  (ctx, ssh, "studio-backend")
12c.Services().Stop   (ctx, ssh, "studio-backend")
13c.Services().Restart(ctx, ssh, "studio-backend")
14c.Services().Remove (ctx, ssh, "studio-backend")
15 
16logs, _ := c.Services().Logs(ctx, ssh, "ollama")

2 examples

vxsdk

cicd

Manage CI/CD pipelines, trigger builds, inspect runs.

1pipelines, _ := c.CICD().Pipelines().List(ctx)
2for _, p := range pipelines { fmt.Println(p.ID, p.Name) }
3 
4c.CICD().Pipelines().Trigger(ctx, "studio-api", "main")
5c.CICD().Builds().Show(ctx, "<build-id>")

1 example

vxsdk

marketplace

agents / models / solutions.

1agents, _ := c.Marketplace().Agents().List(ctx)
2 
3c.Marketplace().Agents().Deploy(ctx, "prompt_agent", marketplace.SSH{
4    Host: "h", User: "ubuntu", KeyPairName: "AWSPRODKEY1.PEM",
5})
6 
7c.Marketplace().Solutions().Provision(ctx, "vault-consul-nginx",
8    marketplace.ProvisionInput{
9        ResourceName: "security-stack",
10        CloudProvider: "aws", Region: "us-east-1",
11        Inputs: map[string]any{"instance_type": "t3.medium"},
12    })

1 example

vxsdk

cloud

VM / S3 / IAM / Database / Kubernetes / Network / Serverless. The VM resource exposes provision + lifecycle (Status / Action) symmetric with the Python and TypeScript SDKs.

1import "github.com/prodxcloud/vxcloud/cloud"
2 
3vm, _ := c.Cloud().VM().Provision(ctx, &cloud.ProvisionVMInput{
4    Provider: "aws", InstanceType: "t3.small", Region: "us-east-1",
5    KeyPairName: "AWSPRODKEY2",
6})
7 
8// Inspect current state (returns raw provider-shaped map)
9state, _ := c.Cloud().VM().Status(ctx, cloud.StatusInput{
10    InstanceID: vm.InstanceID, Provider: "aws",
11})
12fmt.Println(state["state"])
13 
14// Lifecycle action — Action validated against {start|stop|restart|reboot}
15// before any network call; returns *vxerrors.ValidationError for bad input.
16_, err := c.Cloud().VM().Action(ctx, cloud.ActionInput{
17    InstanceID: vm.InstanceID,
18    Action:     "restart",
19    Provider:   "aws",
20})
21if err != nil { panic(err) }

2 examples

vxsdk

agentcontrol (full /api/v2/agentcontrol/* surface — 22 sub-resources)

Full UI parity with /dashboard/?tab=agentcontrol. Original surfaces (FineTuning, Training, Knowledge, Datasets, Agents, GitHub) plus the new sub-resources: Embeddings, Tools, MCP, Evals, Code, Models, Deployments, WebAssets, Benchmarks, Catalog, Health, Events, LLM, DeployTargets, Workflows, Infra. Plus `RuntimeMetrics(ctx, endpoint)` to proxy a marketplace agent's /metrics scrape through the node. Every call sends `X-Tenant-ID` automatically; set `c.AgentControl().TenantID` once at construction.

1import "github.com/prodxcloud/vxcloud/agentcontrol"
2 
3ac := c.AgentControl()
4ac.TenantID = "92efb9b0-…"   // or rely on Client.TenantID
5 
6summary, _ := ac.Summary(ctx)
7fmt.Println(summary["total_models"], summary["active_training_jobs"])
8 
9fts, _   := ac.FineTuning().List(ctx)
10trains, _ := ac.Training().List(ctx)
11kbs, _   := ac.Knowledge().List(ctx)
12dss, _   := ac.Datasets().List(ctx)
13fmt.Printf("FT=%d Train=%d KB=%d DS=%d\n", len(fts), len(trains), len(kbs), len(dss))

6 examples

vxsdk

salesshift (tracked email + the leads pool)

One client, `c.SalesShift()`, with 25 methods: the four email/stats calls and the whole leads pool. That is 20 of SalesShift’s 306 routes and none of its 57 messaging routes — deals, sequences, quotes, contracts, invoices, calendar and deliverability have no SDK method in any language. Fully typed structs for every request and response, plus helpers that exist to stop specific mistakes: `MailableEmail()` hands back an address only when this org revealed it, `NeedsReveal()`, `Lead.Convertible()`, `LeadPage.DisplayTotal()` (which honours the 10,000 display cap) and `ConvertFromPoolReport.Describe()`. Status: read in full for this reference, but not compiled or executed here — the routes behind it were exercised directly and through the Python SDK.

1import "github.com/prodxcloud/vxcloud/salesshift"
2 
3ss := c.SalesShift()
4 
5stats, _ := ss.GetStats(ctx)
6// EmailStats is a map[string]int — sent / delivered / opened / replied /
7// bounced — so a funnel key added server-side does not need an SDK bump.
8fmt.Println(stats.Contacts, stats.EmailStats["opened"])
9 
10emails, _ := ss.ListEmails(ctx, "sent")
11for _, m := range emails {
12    fmt.Println(m.ToEmail, m.Status, m.OpenCount)
13}
14 
15out, err := ss.SendEmail(ctx, salesshift.SendEmailInput{
16    ToEmail:  "[email protected]",
17    Subject:  "Following up, {{first_name}}",
18    BodyHTML: "<p>Saw you shipped v2 — worth 15 minutes?</p>",
19})
20// Suppressed / unsubscribed recipients come back as an error. That gate
21// is not optional, and it is the cheapest bounce you will ever avoid.
22if err != nil { return err }
23fmt.Println(out.TrackingID, out.Provider)
24 
25// The worker runs on YOUR tenant node, not the control plane.
26h, _ := ss.GetWorkerHealth(ctx)
27fmt.Println(h.Status, h.Providers, h.RedisConnected)

5 examples

vxsdk

networks

Catalog of diagnostic scripts + remote execution.

1import "github.com/prodxcloud/vxcloud/networks"
2 
3scripts, _ := c.Networks().List(ctx)
4 
5script, _ := os.ReadFile("./port-check.sh")
6c.Networks().RunRemote(ctx, networks.RunRemoteOpts{
7    SSH: networks.SSH{
8        Host: "h", User: "ubuntu", KeyPairName: "AWSPRODKEY1.PEM",
9    },
10    Script:     script,
11    ScriptName: "port-check.sh",
12    Args:       []string{"443"},
13})

1 example

vxsdk

agents (AI orchestration)

AI-agent surface mirroring `vxcli agent`. Coding / DevOps / Git / parallel + tool dispatch.

1out, _ := c.Agents().Coding(ctx,
2    "Write a FastAPI route that validates a JWT bearer token",
3    "python",
4)
5fmt.Println(out.Output)
6 
7c.Agents().Devops  (ctx, "deploy main of api/ to staging and roll forward")
8c.Agents().Git     (ctx, "draft commit messages for the staged diff")
9c.Agents().Parallel(ctx, "review", "audit this PR for security issues")
10 
11tools, _ := c.Agents().Tools(ctx, "devops")
12c.Agents().Tool(ctx, "docker.list", map[string]any{"host": "h"})

1 example

vxsdk

chat (multi-provider AI)

Provider envelope normalizes 16 AI providers via /api/v2/chat/send.

1import "github.com/prodxcloud/vxcloud/chat"
2 
3out, _ := c.Chat().Send(ctx, chat.SendInput{
4    Provider:  chat.ProviderAnthropic,
5    Model:     "claude-opus-4-7",
6    Messages: []chat.Message{
7        {Role: "system", Content: "You are concise."},
8        {Role: "user",   Content: "What is HCL terraform?"},
9    },
10    MaxTokens: 500,
11})
12fmt.Println(out.Completion)

2 examples

vxsdk

observability

Backups, migrations, batch resource sync.

1bk, _ := c.Observability().Backups().Create(ctx,
2    observability.CreateBackupInput{
3        ResourceID: "rds-abc", ResourceType: "database",
4        BackupName: "pre-migration",
5    })
6 
7list, _ := c.Observability().Backups().List(ctx)
8 
9c.Observability().Backups().Restore(ctx,
10    observability.RestoreBackupInput{
11        BackupID: bk.ID, TargetRegion: "eu-west-1",
12    })
13 
14plan, _ := c.Observability().Migrations().Plan(ctx,
15    observability.PlanMigrationInput{
16        SourceProvider: "aws", TargetProvider: "gcp",
17        Resources: []string{"rds-abc"},
18    })
19c.Observability().Migrations().Execute(ctx,
20    observability.ExecuteMigrationInput{SessionID: plan.SessionID})

1 example

vxsdk

billing

Cost reporting + AI-powered optimization recommendations.

1r, _ := c.Billing().Multicloud(ctx, billing.MulticloudInput{
2    StartDate: "2026-04-01", EndDate: "2026-04-30",
3})
4fmt.Println("Total:", r.TotalUSD)
5for cloud, usd := range r.Breakdown { fmt.Printf("  %s %.2f\n", cloud, usd) }
6 
7opt, _ := c.Billing().Optimization(ctx, billing.OptimizationInput{Provider: "aws"})
8for _, rec := range opt.Recommendations {
9    fmt.Println(rec.Action, "→", rec.Resource)
10}

1 example

vxsdk

workspace setup

/api/v2/setup/* — workspace + organization lifecycle, cloud + AI provider credentials, API tokens, Git/payment/SMTP/SSL/OAuth/OKTA/CyberArk creds.

1import "github.com/prodxcloud/vxcloud/workspace"
2 
3c.Workspace().CreateWorkspace(ctx, workspace.CreateWorkspaceInput{
4    WorkspaceName: "my-org", Region: "us-east-1",
5})
6 
7c.Workspace().StoreAWSCredentials(ctx, workspace.AWSCredentials{
8    AccessKeyID: "AKIA…", SecretAccessKey: "…", Region: "us-east-1",
9})
10 
11tok, _ := c.Workspace().CreateAPIToken(ctx,
12    workspace.CreateAPITokenInput{TokenName: "ci-bot", ExpiresInDays: 90})
13fmt.Println(tok.Token)

2 examples

vxsdk

nodes (list / register self-hosted / update / delete)

Tenant-node CRUD against the VxCloud control plane. The Go SDK mirrors `vxcli node {list,add,update,delete,set-default}` 1:1. Self-hosted (BYO) registration uses POST /api/v1/auth/nodes/self-hosted, partial updates go through PATCH /api/v1/auth/nodes/{id}, deletes via DELETE /api/v1/auth/nodes/{id}.

1import "github.com/prodxcloud/vxcloud/nodes"
2 
3all, _ := c.Nodes().List(ctx)
4for _, n := range all {
5    fmt.Println(n.ID, n.Label(), n.BaseURL(),
6        map[bool]string{true: "DEFAULT", false: ""}[n.IsDefaultNode])
7}
8 
9def, _ := c.Nodes().Default(ctx)
10fmt.Println("default node:", def.Label())
11 
12_ = c.Nodes().SetDefault(ctx, def.ID)

4 examples

vxsdk

errors

Typed error tree — type-assert with `errors.As` to discriminate failure modes.

1import (
2    "errors"
3    vxerrors "github.com/prodxcloud/vxcloud/errors"
4)
5 
6if _, err := c.Deploy().Container(ctx, /* … */); err != nil {
7    var aerr *vxerrors.AuthError
8    var verr *vxerrors.ValidationError
9    switch {
10    case errors.As(err, &aerr):
11        // re-run vxcli auth login
12    case errors.As(err, &verr):
13        // bad input — fix the call
14    case vxerrors.IsRetryable(err):
15        // back off + retry (network / rate-limit / 5xx)
16    default:
17        return err
18    }
19}

1 example

vxsdk

Production notes & known issues

Real failure modes you will hit at least once. Same content as the CLI "Operational gotchas" section, adapted to SDK usage.

1// c.Deploy().Stack("fastapi"/"react"/"nextjs"/...) server-side
2// validates KeyPairName as required and ignores any PEM. Upload once:
3//
4//   vxcli configure setup vm --key-pair-name MYKEY --pem-file ./mykey.pem
5//
6// c.Deploy().Container() accepts deploy.SSH{...KeyPairName...} from Vault
7// OR a local PEM via deploy.SSH{...PrivateKeyPEM: ...}.

4 examples

vxsdk

← Previous SDK

TypeScript SDK

Next SDK →

Terraform Provider

Back to all SDKs CLI reference

Was this page helpful?

Previous⌨️ CLI Reference Next 📖 Guides