[Nabhag8848]

Summary

Add Blaxel as an independently published provider for the shared Go and TypeScript Sandbox Kit clients. Applications can create, look up, run commands in, inspect files in, and delete Blaxel sandboxes through the same client/handle model used by the other providers.

The branch also hardens shared client boundaries across providers: response identity checks, public error context, cancellation and deadlines, input ownership, endpoint validation, and Go credential JSON handling. It adds runnable provider-specific examples and updates the website and Markdown guides for each language.

Native SDKs are pinned to github.com/blaxel-ai/sdk-go@v0.31.0 and @blaxel/core@0.3.36. The provider packages remain separate from the core sandbox package.

Architecture

flowchart LR
  App[Application] --> Client[Shared Kit client]
  Client --> Shared[Shared validation and handle orchestration]
  Shared --> Provider[Blaxel provider]
  Provider --> Checks[Provider validation]
  Provider --> Mapping[Request and response mapping]
  Provider --> Errors[Error classification]
  Mapping --> Native[Official Blaxel SDK]
  Native --> API[Blaxel API]
  Client -. also supports .-> Other[Daytona and Modal providers]

Loading

The provider owns the native SDK and translates its API into Kit types. Shared contract validation runs before provider validation; unsupported intent is rejected before provider calls. Closing a client or handle releases local resources and does not delete a cloud sandbox.

1. Blaxel configuration and creation

• Add Scope.Workspace to the protobuf client contract, regenerate Go/TypeScript contracts, and align the client inventory. Blaxel accepts an API key and workspace, with BL_API_KEY / BL_WORKSPACE fallbacks; create also requires a region.
• Add sdks/go/providers/blaxel and @sandbox-kit/blaxel. The TypeScript provider rejects a second incompatible Blaxel configuration in the same process because the pinned native SDK uses process-wide configuration.
• Require a Blaxel-valid name and image. The returned sandbox ID is the create name. Validate supported memory, labels, environment, ports, outbound domains, maximum lifetime, idle termination, and creation timeout; reject unsupported settings rather than silently dropping them.
• Preserve the documented provider limits: reserved ports 80/443/8080, maximum lifetime of at least five minutes, idle termination of at least one minute, and no HTTP/2 over TLS. CPU/disk overrides, volumes, runtime, isolation and readiness probes are not supported by this integration.

import { blaxel } from "@sandbox-kit/blaxel";
import { Client } from "@sandbox-kit/sandbox";

await using client = new Client({
  provider: blaxel(),
  auth: { apiKey: { key: process.env.BL_API_KEY! } },
  region: "us-pdx-1",
  timeout: 120_000,
});

const sandbox = await client.create({
  name: "kit-example",
  source: { image: { reference: "blaxel/base-image:latest" } },
  resources: { memoryMib: 4096n },
});
console.log(sandbox.id); // kit-example

config := &sandbox.Config{
    Auth: &sandbox.AuthConfig{Credentials: &sandbox.APIKey{
        ApiKey: &sandbox.APIKeyCredentials{Key: os.Getenv("BL_API_KEY")},
    }},
    Region: sandbox.Value("us-pdx-1"),
}
client, err := sandbox.NewClient(blaxel.New(), config)
if err != nil { log.Fatal(err) }
defer client.Close(context.Background())

instance, err := client.Create(context.Background(), &sandbox.CreateOptions{
    Name: sandbox.Value("kit-example"),
    Source: &sandbox.SandboxSource{Kind: &sandbox.Image{
        Image: &sandbox.ImageSource{Reference: "blaxel/base-image:latest"},
    }},
})
if err != nil { log.Fatal(err) }
fmt.Println(instance.ID()) // kit-example

2. Lifecycle, process, and filesystem

Blaxel supports get/refresh, delete, and close; it does not expose Kit attach, start, stop, pause, archive, or terminate. Active and idle states map to running and paused. Successful delete reports deleted and terminal. Without wait, delete returns when accepted; with wait, Kit polls until the resource is removed or reports deleted.

flowchart TD
  A[Delete by sandbox name] --> B[Native delete]
  B --> C{wait requested?}
  C -->|no| D[Return deleted / terminal]
  C -->|yes| E[Poll lookup]
  E --> F{Not found or deleted?}
  F -->|no| E
  F -->|yes| D

Loading

Process calls accept argv or shell, return exit code/stdout/stderr, and treat nonzero exit codes as results. Arguments are shell-quoted for Blaxel's command interface. A positive Blaxel process timeout must be whole seconds; omitted or zero disables the native process time limit. Cancellation ends the caller's wait, but a remote command may continue.

const result = await sandbox.process.run({ argv: ["printf", "%s", "hello world"] });
console.log(result.exitCode, new TextDecoder().decode(result.stdout));

await sandbox.filesystem.writeFile("/tmp/note.txt", new TextEncoder().encode("hello"));
const info = await sandbox.filesystem.stat("/tmp/note.txt");
await sandbox.delete({ wait: true });

Filesystem support includes read/write, local copy in/out, mkdir, list, stat, and remove. Paths inside the sandbox must be absolute; mkdir defaults to creating parents and rejects parents: false. Stat maps the type and size plus permissions/owner/group/modified time when reported. Local copy failures identify local_path when applicable.

3. Errors, cancellation, and provider behavior

• Map Blaxel public statuses and provider codes to Kit error kinds, retaining native causes. Examples include AlreadyExists for an existing create name, Conflict while deletion is still completing, NotFound for missing resources, and Timeout/Canceled for wait failures.
• Validate response IDs and provider identity at create, lookup, and lifecycle boundaries; reject missing or mismatched identities as invalid responses. TypeScript errors report the public operation (for example, get, even when the provider uses refresh internally).
• Capture caller-owned TypeScript create/config/process/filesystem inputs before provider dispatch or queueing, copy file-write bytes in both languages, and preserve per-handle serialization after cancellation until in-flight work settles.
• Preserve cancellation causes and observe late provider rejections. TypeScript deadlines above Node's maximum single timer are scheduled in segments; Go and TypeScript endpoint checks align on the covered loopback/user-info cases.
• Blaxel create HTTP 504 has a native SDK difference: Go returns a timeout at the edge response; TypeScript may keep waiting until readiness or its deadline. A timeout does not prove creation failed: look up the sandbox by name before retrying.

import { ErrorKind, SandboxError } from "@sandbox-kit/sandbox";

try {
  await client.get("kit-example");
} catch (error) {
  if (error instanceof SandboxError && error.kind === ErrorKind.NotFound) {
    console.error(error.operation, error.provider); // get, blaxel
  } else {
    throw error;
  }
}

4. Credential serialization

Go credential pointers implement encoding/json redaction, including credentials nested in the usual *sandbox.Config. OAuth output retains only the client ID. This affects JSON output, not the credential passed to the provider.

Known limitation: marshaling an individual credential value directly with encoding/json can expose its fields; pointer redaction does not apply. Protobuf protojson also serializes schema fields. Avoid serializing credential values/configuration with those paths. Resolving value serialization completely requires a broader decision about the public protobuf-based credential representation.

5. Documentation, examples, and tooling

• Add independent Go and TypeScript Blaxel examples for configuration, lifecycle, filesystem, process, and error handling, with their own configuration and dependencies.
• Add the Blaxel provider page and update shared website/Markdown guides, API references, provider selectors, and examples. Separate Go and TypeScript content when language-specific behavior differs.
• Update documentation authoring guidance for SDK callers; register Blaxel modules and examples with the repository's Go and TypeScript verification commands.

Verification

• Full repository Go verification, including provider modules and examples, during branch development.
• Full TypeScript build/test workflow, including contracts, core, all providers, and examples, during branch development.
• Protobuf format/lint/compilation checks after the contract changes.
• Latest shared-client changes: TypeScript core build and 72 tests; Go sandbox tests with the race detector.
• Provider-focused local tests cover mapping, validation, lifecycle, process, filesystem, errors, and cancellation. Tests use doubles/local servers where appropriate; they do not establish live cloud behavior.
• PR-reported Docs build and Entire Gates pass at the current head; Docs deployment is skipped.

[Nabhag8848]

@cursoragent review it. is there anything which is wrongly wired. check provider docs and lets us know.

[cursor]

Yes — a few things are wrongly wired or inconsistent with Blaxel’s docs.

Real wiring issues

1. Ports example uses reserved ports — 443 / 8080 in create-blaxel-with-ports (Blaxel reserves 80, 443, 8080).
2. Create timeout — Blaxel supports it; TS maps it; Go rejects as unsupported.
3. Go missing floors TS already enforces (max-age ≥ 5m, idle ≥ 1m, memory ≥ 256 MiB).
4. Post-delete info — Go marks Deleted/terminal; TS returns the pre-delete snapshot.
5. Standby state — Go maps DEPLOYED+standby → Paused; TS often still shows Running.

Docs/site

• Shared website guides mostly lack Blaxel <ForProvider> blocks (switcher goes blank).
• docs/providers.md overstates “region required” (Blaxel: optional today / via BL_REGION; Go forces it, TS doesn’t).
• Config scope docs omit workspace.

Fine as designed: native create (not createIfNotExists), get/refresh by name, no start/stop/pause/archive/terminate.

Full write-up is on PR #44. Say if you want those fixed on this branch.

  

[cursor]

Review: Blaxel wiring vs provider docs

Reviewed Go/TS providers against Blaxel sandbox docs and our published READMEs/site. Core create/get/delete/FS/run shape matches the locked decisions (native create, not createIfNotExists; apiKey + workspace; get/refresh by name). Several real mismatches:

Wrong / risky wiring

1. Ports example uses Blaxel-reserved ports
   create-blaxel-with-ports publishes 443 and 8080. Blaxel docs: ports 80, 443, and 8080 are reserved. That example will fail or collide at create time. Use something like 3000 / 3001 instead.

2. Go rejects create timeout; TS maps it; Blaxel supports it
   Blaxel SDKs accept a per-create timeout (seconds) and raise a creation-timeout error when exceeded.

   • TS: maps provisioning.timeout (1–50 whole seconds)
   • Go: rejects as unsupported (“not mapped”)
     So the same Kit call succeeds in TS and fails in Go. Go should map this (or both languages should reject it consistently and docs should say so).

3. Go missing Blaxel duration / memory floors that TS enforces

   • Max-age TTL minimum 5m and idle TTL minimum 1m: TS rejects below these; Go only checks “whole seconds” and can send values Blaxel rejects upstream.
   • Memory floor 256 MiB: TS rejects; Go does not.

4. Delete metadata after success

   • Go: sets State=Deleted, Terminal=true after delete.
   • TS: returns the pre-delete mapSandboxInfo snapshot (still looks running). Callers checking info().terminal / state after delete({ wait: true }) get different answers per language.

5. Standby / DEPLOYED state mapping
   Blaxel DEPLOYED can be active or standby. Go uses Status + State (DEPLOYED + standby → Paused). TS maps status DEPLOYED → Running and only treats STANDBY if that string is the status. Standby sandboxes can look “Running” in TS.

Docs / site gaps (not runtime bugs, but wrong for the Blaxel switcher)

6. Shared website guides mostly omit Blaxel <ForProvider> blocks
   index.mdx, configuration.mdx, create.mdx, lifecycle.mdx, filesystem.mdx, process.mdx, errors.mdx still only switch Daytona/Modal. Selecting Blaxel in the docs control leaves those pages without install/create snippets. blaxel.mdx + examples catalog exist; the shared matrices do not.

7. docs/providers.md says “Blaxel requires region”
   Blaxel docs: region is optional today (also via BL_REGION), recommended, becoming mandatory later.

   • Go Kit: requires Config.Region on create (stricter than Blaxel).
   • TS Kit: optional if omitted.
     The providers page overstates “required” for both languages.

8. configuration.mdx scope line still says “App, environment, or organization” — no workspace.

Intentionally fine (not bugs)

• Using native create instead of Blaxel’s recommended createIfNotExists matches the locked decision.
• get/refresh by name is wired correctly (Go SandboxRefresher → Client.Get; TS backend.refresh).
• Start/stop/pause/archive/terminate unsupported is correct for Blaxel’s auto standby model.
• Endpoint rejection + apiKey-only auth match Blaxel’s env/constructor model.

Happy to patch (1)–(5) and fill the site ForProvider gaps in a follow-up on this branch if you want.

[Nabhag8848]

@cursoragent can u look at other solution of provider + also seee other implementation within same codebase. get all the sdks of provider we have impleemented or not.

then check and go ahead with what recommend. just take decision based on if u implement this if it creates more technical debt don't do it (thats the one of the way u verify that u are thinnking write way)

go ahead.

[cursor]

Compared Blaxel against Modal/Daytona and the native Blaxel SDKs, then only shipped fixes that cut Go↔TS drift without inventing unsupported APIs.

Shipped in #45 → feat/blaxel-provider:

• Ports examples: 3000/3001 (not reserved 443/8080)
• Go memory ≥256 + TTL floors (5m / 1m) to match TS
• TS delete returns Deleted + terminal like Go
• Idle-disable rejected in TS (was silently omitted)
• Region/scope docs + config setup link

Skipped (would add debt):

• Go create-timeout — Go SDK has no create-timeout option
• TS standby — SandboxInstance has no public state
• Full shared-guide ForProvider matrix — permanent doc surface; blaxel.mdx already covers Blaxel

Waiting on CI for cursor/blaxel-wiring-fixes-7ca2.

  

[cursor]

Went through Modal/Daytona + Blaxel SDKs and shipped the low-debt alignments on cursor/blaxel-wiring-fixes-7ca2 (PR into this branch).

Did: reserved-ports examples, Go TTL/memory floors, TS delete terminal state, idle-disable reject, region/scope docs.

Skipped on purpose: Go create-timeout (no native API), TS standby (no public state on SandboxInstance), full shared-guide ForProvider matrix (ongoing doc debt; blaxel.mdx already exists).

[Nabhag8848]

@cursoragent review again. check for everything that looks incorrect, wrong validations, wrong decisions, code smells, wrong ownership in code.

look trhough and recommend. all the decisions should be backed by stromg valid reasons with proof u have checked provider sdks

[cursor]

Second-pass review is on #44, checked against @blaxel/core@0.3.35, sdk-go@v0.31.0, Blaxel docs, and Daytona/Modal.

Must-fix: TS WaitCondition.Ready calls deprecated no-op sandbox.wait(), while also requiring provisioning.timeout and forwarding it as Blaxel’s destructive create timeout (1–50s). Go already rejects Ready — TS should match and only map create timeout as create timeout.

Keep (proven): max-age → runtime.ttl (≥5m), idle → ttl-idle (≥1m), native create, TS create-timeout 1–50, Go rejecting create-timeout (no Go API), region/lifecycle choices.

Weak/wrong validations: memory ≥256 has no SDK/API proof — confirm or drop. Reserved ports still accepted by the provider (examples only were fixed).

Ownership smells: process-global settings.setConfig; Go Stat bypasses instance.FS; 409 Conflict vs AlreadyExists asymmetry.

Say if you want a follow-up PR for Ready + the 256 floor.

  

[cursor]

Second review (post-#45) — SDK-backed

Pinned SDKs checked: @blaxel/core@0.3.35, github.com/blaxel-ai/sdk-go@v0.31.0, plus Blaxel docs (Expiration, Overview, create API). Compared to in-repo Daytona and Modal providers.

Must-fix / wrong decision

1. WaitCondition.Ready is dead / misleading (TS)

Proof (@blaxel/core sandbox.js):

async wait({ maxWait = 60000, interval = 1000 } = {}) {
  logger.warn("⚠️  Warning: sandbox.wait() is deprecated. You don't need to wait for the sandbox to be deployed anymore.");
  return this;
}

Kit still maps waitFor: Ready → waitUntilReady: true → sandbox.wait({ maxWait }), and requires provisioning.timeout for that path. That timeout is also forwarded as Blaxel create options.timeout (1–50s, X-Blaxel-Creation-Timeout), which cancels and deletes the sandbox on deadline (SandboxCreationTimeoutError / MAX_CREATION_TIMEOUT_SECONDS = 50).

So Ready conflates three different things: a no-op deprecated wait, a required Kit timeout, and a destructive creation deadline.

Go already rejects any non-default WaitFor. That is the safer ownership.

Recommend: Reject WaitCondition.Ready in TS (match Go), and map provisioning.timeout only as Blaxel create timeout when set (Default/Scheduled wait). Drop waitUntilReady / sandbox.wait usage.

Correct — keep (with proof)

Behavior	Proof
maximumLifetime → runtime.ttl (max-age), floor 5m	Go SDK: “Max-age… minimum '5m'”; Expiration docs same
idleTerminate → lifecycle.expirationPolicies ttl-idle, floor 1m	Go SDK + Expiration docs (“ttl-idle… minimum 1m”)
Native create / NewInstance, not createIfNotExists	Locked Kit decision; both SDKs expose both
Create timeout TS 1–50s	@blaxel/core MAX_CREATION_TIMEOUT_SECONDS = 50 + validateCreateOptions
Go rejects create timeout	Go NewInstance has no create-timeout option / no X-Blaxel-Creation-Timeout helper
Region: Go requires Config.Region; TS optional	Go SDK NewInstance requires region or BL_REGION; Kit Go fails closed; TS can omit and let env/SDK fill
No start/stop/pause/archive/terminate	Blaxel auto standby; SDKs have no Kit-equivalent lifecycle ops
Delete → Deleted + terminal (both langs after #45)	Matches Go path + Daytona “terminal after delete” intent
Ports examples 3000/3001	Overview: 80/443/8080 reserved

Wrong or weak validations

2. Memory floor 256 MiB — unproven

Enforced in Go + TS provider_checks and README (“Blaxel requires at least 256”). Create API schema documents memory as integer (example 4096) with no minimum. Neither pinned SDK validates 256 client-side.

Recommend: Confirm against Blaxel support/API error for memory: 128, or drop the floor until proven. Speculative floors are debt.

3. Reserved ports not rejected in the provider

Examples fixed, but create still maps 443/8080 (see Go rejection_test happy path). Blaxel will fail later. Soft recommend: reject 80/443/8080 early like other “outside supported values” checks — low debt, matches docs.

Ownership / smells (judgement)

4. TS settings.setConfig is process-global

BlaxelProvider calls settings.setConfig(config) from @blaxel/core. Two Kit clients in one process clobber each other. This is Blaxel’s SDK model (no per-instance client like Go blaxel.NewClient(opts...)). Document the limit; don’t invent a fake isolated client without SDK support.

5. Go Stat bypasses instance.FS

Rebuilds SandboxFilesystemService with WithBaseURL while other FS ops use instance.FS.*. SandboxInstanceFSService has no public Get/Stat; Get lives on the lower service. Works, but duplicated URL ownership vs the instance handle. Prefer one path if the SDK grows a public metadata call; until then, leave or add a short comment why.

6. Go 409 → Conflict vs TS SANDBOX_ALREADY_EXISTS → AlreadyExists

Go errors.go status switch maps 409 → Conflict and does not special-case already-exists codes (Go apierror constants are gateway-only). TS maps control-plane codes to AlreadyExists. Same failure, different Kit kinds. Align when a stable Go code is available.

7. errors.ts local FS helpers — same shape as Daytona/Modal. Not a Blaxel-specific smell; leave.

Still intentionally skipped (debt)

• Full shared-guide <ForProvider> matrix (dedicated blaxel.mdx exists)
• TS standby via private SandboxInstance fields (no public state getter; Go has Sandbox.State)
• Fake Go create-timeout via context.WithTimeout (wrong semantics vs Blaxel delete-on-timeout)

Suggested follow-up order

1. Fix Ready / create-timeout conflation (TS)
2. Prove or remove 256 MiB floor
3. Optional: reserved-port precheck; AlreadyExists alignment; document global settings

I can ship (1)–(2) on a small PR into this branch if you want.

[Nabhag8848]

@cursoragent what all decisons u need from me which u are confused

[cursor]

Only three need your call — everything else I already have a recommendation for:

1. Memory ≥256 — drop until Blaxel proves it (A, my lean) or keep as Kit policy (B)?
2. Reserved ports — pre-reject 80/443/8080 in the provider (A) or leave to Blaxel (B)?
3. Polish (global settings note, 409→AlreadyExists, Stat comment) — include now (A) or defer (B)?

No decision needed: I’ll fix TS WaitCondition.Ready (reject + map create timeout only) unless you say stop.

Reply like 1A 2A 3B or “ship Ready only”.

  

[cursor]

Not confused on most of it — only these need a call from you:

Need your decision

1. Memory floor 256 MiB — keep or drop?

   • No proof in Blaxel API/SDK that 256 is real.
   • A) Drop the floor in Go+TS until Blaxel documents it (my lean)
   • B) Keep as Kit policy even without Blaxel proof

2. Reserved ports (80 / 443 / 8080) — pre-reject in provider?

   • Examples already use 3000/3001.
   • A) Reject early in create mapping (low debt)
   • B) Leave to Blaxel API errors

3. Optional polish this PR vs later

   • Document TS global settings.setConfig limit
   • Align Go 409 → AlreadyExists when code is SANDBOX_ALREADY_EXISTS
   • Comment on Go Stat dual path
   • A) Include with the Ready fix
   • B) Defer

No decision needed — I’ll do this unless you say stop

• Reject TS WaitCondition.Ready (match Go); map provisioning.timeout only as Blaxel create timeout; remove no-op sandbox.wait

Not asking you (already decided / won’t do)

• No fake Go create-timeout
• No private-field TS standby mapping
• No full shared-guide ForProvider matrix

Reply with e.g. 1A 2A 3B (or “ship Ready only”) and I’ll open the follow-up PR.

[Nabhag8848]

@cursoragent go ahead with what u recommend and lean to I will review it before merge if there are things which needs more decisions implement all of it

[cursor]

Shipped as 1A / 2A / 3A in #46 → feat/blaxel-provider:

• Reject TS WaitCondition.Ready; create timeout only as create timeout
• Drop unproven 256 MiB floor
• Pre-reject ports 80/443/8080
• AlreadyExists alignment, Stat comment, global settings note

Waiting on CI for your review before merge.

  

[cursor]

Shipped recommended leans as 1A / 2A / 3A on cursor/blaxel-review-fixes-7ca2 (PR into this branch):

• Reject TS WaitCondition.Ready; create timeout only as create timeout
• Drop unproven 256 MiB floor
• Pre-reject reserved ports 80/443/8080
• AlreadyExists alignment, Stat comment, global settings note

Please review before merge.

[cursor]

Soft-debt polish from the third-pass review is in #48 → this branch: dead create options, native projectHandle for standby, bare 409 → AlreadyExists, Go Stat ownership comment, and matching docs/website updates.