Sandbox

Templates

Build reusable, declarative Tenki Sandbox environments with templates. Pre-install toolchains, prepare repos, and spin up identical sessions on demand.

Templates turn a one-off session into a reproducible environment your whole team can share. A template captures a base image, a setup script, and optional defaults. When you build the template, Tenki runs the setup script and snapshots the result, so any session created from that template restores the snapshot in seconds.

Use templates when you want:

  • pre-installed toolchains
  • prepared repositories or working directories
  • background processes already started
  • repeatable onboarding or dev boxes
  • many similar sessions from one prepared environment

Data model

A template contains:

  • name
  • workspace_id
  • base_image_id (default: sandbox)
  • setup_script
  • optional start_cmd
  • env_vars
  • optional default CPU and memory
  • latest_build

Validation: name length 1..64, list page size <= 100.

Build lifecycle

A template record is not itself bootable. You build it first. A build:

  1. boots an internal build session
  2. runs the template setup_script
  3. optionally starts start_cmd
  4. captures a VM snapshot
  5. marks the build READY

Build states: PENDING, BUILDING, READY, FAILED.

A template is usable for create only after a build reaches READY. The latest READY build is what new sessions restore from.

CLI workflow

Create

tenki sandbox template create \
  --workspace <workspace-id> \
  --name node-api \
  --base-image sandbox \
  --setup-script 'apt-get update && apt-get install -y jq && mkdir -p /workspace/app' \
  --start-cmd 'bash -lc "cd /workspace/app && npm run dev"' \
  --env APP_ENV=dev \
  --cpu 2 \
  --memory-mb 4096

List, get, update, delete

tenki sandbox template list --workspace <workspace-id>
tenki sandbox template get <template-id>
tenki sandbox template update <template-id> --start-cmd 'bash -lc "cd /workspace/app && npm run start"'
tenki sandbox template delete <template-id>

Build

tenki sandbox template build <template-id> --wait

Create a session from a template

tenki sandbox create --template <template-id> --name reviewer-a

The latest READY build is restored. Template environment variables are applied. Template CPU/memory defaults are inherited unless you override them.

Go SDK

template, err := client.CreateTemplate(
  ctx,
  tenkisandbox.WithWorkspaceID(workspaceID),
  tenkisandbox.WithTemplateName("go-dev"),
  tenkisandbox.WithBaseImageID("sandbox"),
  tenkisandbox.WithSetupScript("apt-get update && apt-get install -y ripgrep"),
  tenkisandbox.WithStartCmd("bash -lc 'sleep infinity'"),
  tenkisandbox.WithEnvs(map[string]string{"GOFLAGS": "-mod=mod"}),
  tenkisandbox.WithTemplateResources(2, 4096),
)

build, err := client.BuildTemplate(ctx, template.ID)
build, err = client.WaitForTemplateBuild(ctx, build.ID)

template, err  = client.GetTemplate(ctx, template.ID)
templates, err := client.ListTemplates(ctx, workspaceID)
template, err  = client.UpdateTemplate(ctx, template.ID, tenkisandbox.WithStartCmd("bash -lc 'sleep infinity'"))
template, err  = client.DeleteTemplate(ctx, template.ID)
build, err     = client.GetTemplateBuild(ctx, build.ID)

session, err := client.Create(
  ctx,
  tenkisandbox.WithTemplate(template.ID),
  tenkisandbox.WithName("my-devbox"),
)

TypeScript SDK

const template = await sandbox.createTemplate({
  workspaceId: "ws-123",
  name: "node-20",
  setupScript: "apt-get update && apt-get install -y nodejs",
});

const build = await sandbox.buildTemplate(template.id);
await sandbox.waitForTemplateBuild(build.id);

const session = await sandbox.createAndWait({
  templateId: template.id,
});

Build logs

A build record includes:

  • version
  • error
  • build_log_tail
  • build_log_truncated
  • build_log_artifact_id
  • started_at, completed_at
  • snapshot_id, session_id

Behavior today:

  • build_log_tail stores only the DB tail, capped at 128 KiB
  • the full build log is stored as a gzipped artifact when artifact storage is configured
  • build_log_artifact_id points to that full log artifact

There is no first-class CLI wrapper for downloading the full log artifact yet. If you need it, use the public GetArtifactDownloadUrl RPC directly with your own Connect or gRPC client.

End-to-end example

tenki sandbox template create \
  --workspace <workspace-id> \
  --name review-env \
  --setup-script 'apt-get update && apt-get install -y ripgrep jq git' \
  --start-cmd 'bash -lc "sleep infinity"' \
  --cpu 2 \
  --memory-mb 4096

tenki sandbox template build <template-id> --wait

tenki sandbox create --template <template-id> --name reviewer-a
tenki sandbox create --template <template-id> --name reviewer-b

Discover the workspace ID first if you don't already have it:

identity, err := client.WhoAmI(ctx)
workspaceID := identity.Workspaces[0].ID

Volumes and templates

Templates do not auto-attach volumes

A template captures VM state, not external volumes. Sessions created from a template are normal sessions. Pass --volume on create if you need persistent data attached.

Errors

  • ErrTemplateNotFound
  • ErrTemplateExists
  • ErrTemplateBuildNotFound
  • ErrTemplateBuildFailed
  • ErrTemplateBuildInProgress
if errors.Is(err, tenkisandbox.ErrTemplateBuildInProgress) {
  // build is still running, wait or retry later
}
LinkedInProduct Hunt